https://wiki.roll20.net/api.php?action=feedcontributions&user=5004103&feedformat=atomRoll20 Wiki - User contributions [en]2024-03-28T23:54:19ZUser contributionsMediaWiki 1.20.3https://wiki.roll20.net/Script:ScriptCardsScript:ScriptCards2022-03-13T15:51:49Z<p>5004103: /* Assign Variable to Built-In Function (--~) */</p>
<hr />
<div>{{revdate}}<br />
{{script overview<br />
|name=ScriptCards<br />
|author=[[Kurt J.]]<br />
|code=ScriptCards<br />
|version=1.6.4<br />
|lastmodified=2022-02-27}}<br />
<br />
== Introduction ==<br />
'''ScriptCards''' provides a feature-rich scripting language built as a Roll20 API script and accessible via the Roll20 chat window and macro system. The normal ScriptCards output is a formatted "card" to the game's {{Text Chat}}. While the visual style of the default output is themed after a D&D 4E Power Card, there is nothing game system specific in ScriptCards. The output is fully customizable, and entirely optional. Scripts can perform game object manipulation and never display anything if desired.<br />
<br />
The ScriptCards language supports variables, looping, conditional statements, branching, functions/subroutines, persistence of data items, object modification, reentrant functionality and much, much more. It includes its own dice roll parser with a number of different rolling options.<br />
<br />
ScriptCards is not game-system specific, and can be used with any system/sheet.<br />
<br />
Current [https://github.com/Roll20/roll20-api-scripts/tree/master/ScriptCards OneClick] Version: '''1.6.4'''<br />
<br />
Current Development Version : '''1.6.5'''<br />
<br />
'''''Note:''''' The documentation below is in the process of being updated for 1.6.2 & later.<br />
<br />
'''''<big>Critically Important: ScriptCards does not parse [[Inline|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.</big>'''''<br />
<br />
=== Links ===<br />
* {{fpl|9752053/ ScriptCards thread on the Roll20 API forum}}<br />
** {{fpl|10000297/ Scritpcard API Working and Sharing thread}}<br />
* [https://github.com/kjaegers/ScriptCards/blob/main/ScriptCards_API/changelog.txt Changelog]<br />
* {{repo|kjaegers/ScriptCards/tree/main/ScriptCards_API ScriptCards_API}} - GitHub repository for source before the one-click version is updated.<br />
* {{repo|kjaegers/ScriptCards/tree/main/ScriptExamples ScriptCards Samples}} - Branch of the GitHub repo that contains sample scripts.<br />
* [https://discord.gg/jSB4wTNpXb Discord Channel]<br />
* {{yt.be|hyR7Jnq4mQM ScriptCards Intro}} 45min, Jan 2021<br />
* {{yt.be|u50xvNzS9Zk ScriptCards Magic Missile Deep Dive}} 39min, Feb 2021<br />
{{#evp:youtube|hyR7Jnq4mQM|[[Script:ScriptCards|ScriptCards]] Introduction|right|770}}<br />
__TOC__<br />
<br />
=== Is ScriptCards Related to [[PowerCards]]? ===<br />
<br />
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.<br />
<br />
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 ({{code|name}}, {{code|leftsub}}, {{code|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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
Check the '''[[#What to Know if you are Coming from PowerCards|What to Know if you are Coming from PowerCards]]'''-section for a comparison table between the two scripts.<br />
<br />
=== What is a ScriptCard Script ===<br />
<br />
A ScriptCard script is text written into the {{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 [[Text Chat|chat window]]. A ScriptCard script is composed of an [[API]] command: <code><nowiki>!scriptcard {{ }}</nowiki></code> 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:<br />
<br />
<pre>!scriptcard {{ }}</pre><br />
<br />
Will produce just a title card that displays “ScriptCards” as the name:<br />
<br />
[[File:Scriptcard blank.png]]<br />
<br />
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 <code><nowiki>{{</nowiki></code> and <code><nowiki>}}</nowiki></code> that direct the API script as to what it should do.<br />
<br />
== Structure of a ScriptCard Line ==<br />
<br />
All ScriptCard lines begin with two dashes, followed by an ''statement identifier character'' that lets ScriptCards what type of line it is. There are many different types of statements, and the bulk if this Wiki entry is dedicated to covering the use and function of each one. <br />
<br />
After the line type identifier, a Tag name 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.<br />
<br />
Following the Tag is a vertical bar, and then the content of the line itself. Again, each type of line might interpret this content differently.<br />
<br />
Example:<br />
<br />
<pre>--#title|Longsword Attack</pre><br />
<br />
In this example:<br />
* '''#''' is the statement identifier character, indicating that this line will be a "settings" statement.<br />
* '''title''' is the Tag name. For the "#" statement type, this indicates what setting we will be updating.<br />
* '''|''' separates the Tag from the Content<br />
* '''Longsword Attack''' is the Content portion of the statement. In this case, it indicates what will be placed in the "title" setting.<br />
<br />
=== Statment Types Quickreference ===<br />
<br />
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.<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Identifier !! Statement Type !! Tag !! Content !! Notes<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--/</nowiki> || Comment || unused || unused || The <code>--/</code> 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--#</nowiki> || 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").<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--+</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--=</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--&</nowiki> || Assign String 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. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--@</nowiki> || 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 (i.e., [[TokenMod|!token-mod]], or [[ChatSetAttr|!setattr]], etc.)<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--:</nowiki> || 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<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--^</nowiki> || Branch To || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--></nowiki> || Call Procedure || 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<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--<</nowiki> || 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.<br />
|- <br />
| style="white-space:nowrap" | <nowiki>--?</nowiki> || Conditional Branch || Condition to be evaluated || True Branch Label<nowiki>|</nowiki>False Branch Label || The condition will be evaluated and execution will jump to one of the two indicated branches (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 included a semicolon separated list of parameters. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--s</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--l</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--v</nowiki> || 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+'''''<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--a</nowiki> || Play Audio Track || Unused || Jukebox track name (case sensitive) || Plays an audio track by name from the Roll20 jukebox. '''''Requires v1.5.2+'''''<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--e</nowiki> || Echo to Chat || Name to send chat command as || Chat message to send || Variable substitution takes place on the tag and content.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--R</nowiki> || Retrieve Repeating Section Row information || "find", "first", or "next" || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--~</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--c</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--i</nowiki> || Information Request || User Prompt;Button Caption || InfoType;VariableName;ParameterText || See full documentation below.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--d</nowiki> || 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. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--%</nowiki> || 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. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--*</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--!</nowiki> || Object Modification || <objectType>:<objectId> || setting:value|setting:value|setting:value... || Set properties of tokens/characters or character attributes ('''''v1.5.0+ required''''')<br />
|}<br />
<br />
== ScriptCard Statement Type Details ==<br />
The sections below detail the individual statement types supported by ScriptCards<br />
<br />
=== Comment (--/) ===<br />
<br />
A --/ statement is ignored by the ScriptCards parser. You can use this type of statement to add comments and informational text to your script. <br />
<br />
Example:<br />
<pre><br />
!script {{<br />
--/|Script Name : Fireball<br />
--/|Purpose : Allow the player to cast a fireball and blow stuff up!<br />
.<br />
.<br />
.<br />
}}<br />
</pre><br />
<br />
=== Set Parameter (--#) ===<br />
<br />
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.<br />
<br />
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.<br />
<br />
'''''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.'''''<br />
<br />
Examples:<br />
<pre><br />
--#title|Magic Missile<br />
--#leftsub|Level 1 Spell<br />
--#rightsub|Force Damage<br />
</pre><br />
<br />
The three examples above set the “title”, “leftsub”, and “rightsub” values for the card to the content value for the line. <br />
<br />
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.<br />
Settings Lines do not produce output lines on the card.<br />
<br />
The following settings are available (note that parameter names are ''not'' case sensitive):<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Name !! Effect/Use !! Default Value !! Type<br />
|-<br />
| 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<br />
|-<br />
| allowplaintextinrolls || If set to a non-zero value, plain character text in rolls will be copied to the roll text || 0 || Per-Line<br />
|-<br />
| bodyFontFace || Name of the font used in the card rows || Helvetica || Global<br />
|-<br />
| bodyFontSize || Size of the text in the card rows || 14px || Global<br />
|-<br />
| bodybackgroundimage || Specify an image (content for a CSS background-image tag) for the body area || none || Global<br />
|-<br />
| buttonBackground || Background color for buttons created with [button][/button] || #1C6EA4 || Per-Line<br />
|-<br />
| buttonBackgroundImage || A CSS specifier for a background image to use for buttons (i.e. url(...);) || empty || Per-Line<br />
|-<br />
| buttonBorderColor || Border (outline) color for buttons created with [button][/button] || #999999 || Per-Line<br />
|-<br />
| buttonFontFace || Font Family specifier for captions on buttons created with [button][/button] || Tahoma || Per-Line<br />
|-<br />
| buttonFontSize|| Text size for captions on buttons created with [button][/button] || x-small || Per-Line<br />
|-<br />
| buttonTextColor|| Text color of labels on buttons created with [button][/button] || #FFFFFF || Per-Line<br />
|-<br />
| 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<br />
|-<br />
| deferralcharacter || Changes the meta script deferral sequence to the specified value || ^ || Per-Line<br />
|-<br />
| diceFontColor|| Color of the dice created with the [d4] [d6], etc. formatting markers || #1C6EA4 || Per-Line<br />
|-<br />
| dicefontsize || Size of the dice created with the [d4] [d6], etc. formatting markers || 3.0em || Per-Line<br />
|-<br />
| 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<br />
|-<br />
| disablerollprocessing || If set to a non-zero value, --= lines will not process dice rolls strings || 0 || Per-Line<br />
|-<br />
| emoteBackground || Background color of the emote area || #f5f5ba || Global<br />
|-<br />
| emoteFont || Name of the font used in emote area (above the title of the output card) || Georgia || Global<br />
|-<br />
| emoteFontColor || Color of the font in the emote area || None (Empty) || Global<br />
|-<br />
| emoteFontSize || Size of the font used in the emote area || 14px || Global<br />
|-<br />
| emoteFontWeight || Font weight for the font in the emote area || bold|| Global<br />
|-<br />
| emoteState || If set to anything other than "visible", the emote portion of the card will not be displayed || visible || Global<br />
|-<br />
| emoteText || Text to display in the emote portion of the card || None (Empty) || Global<br />
|-<br />
| emotefont || Name of the font used in the emote text area || font-family: Georgia, serif; font-weight: bold; || Global<br />
|-<br />
| evenRowBackground || Hex code for the background color for even rows || #eeeeee || Per-Line<br />
|-<br />
| evenRowFontColor || Hex code for the text color for even rows || #000000 || Per-Line<br />
|-<br />
| evenrowbackgroundimage || Specify an image (content for a CSS background-image tag) for the even card rows || none || Per-Line<br />
|-<br />
| executionlimit || Maximum number of script lines the interpreter will try to execute. This prevents "infinite loop" sandbox crashes || 40000 || Global<br />
|-<br />
| hideCard || If set to any non-default value, the entire card output will be suppressed || 0 || Global<br />
|-<br />
| 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<br />
|-<br />
| 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<br />
|-<br />
| lineheight || Vertical size of each line on the output card || normal || Per-Line<br />
|-<br />
| nominmaxhighlight || If set to anything other than "0", rolls will not display crit/fumble/mixed highlight colors. || 0 || Per-Line<br />
|-<br />
| 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<br />
|-<br />
| oddRowBackground || Hex code for the background color for even rows || #d0e4f5 || Per-Line <br />
|-<br />
| oddRowFontColor || Hex code for the text color for odd rows || #000000 || Per-Line<br />
|-<br />
| oddrowbackgroundimage || Specify an image (content for a CSS background-image tag) for the odd crd rows || none || Per-Line<br />
|-<br />
| reentrant || Used to name a script for rentrant button use || 0 || Global<br />
|-<br />
| 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)0 || Global<br />
|-<br />
| rollhilightcolorboth || Background box hilight color if both a 1 and a max on the die are rolled ('''''1.4.4+''''') || #8FA4D4 || Per-Line<br />
|-<br />
| rollhilightcolorcrit || Background box hilight color if the maximum number on the die was rolled ('''''1.4.4+''''') || #88CC88 || Per-Line<br />
|-<br />
| rollhilightcolorfumble || Background box hilight color if a 1 was rolled ('''''1.4.4+''''') || #FFAAAA || Per-Line<br />
|-<br />
| rollhilightcolornormal || Background box hilight color if neither a 1 or a max on the die are rolled ('''''1.4.4+''''') || #FFFEA2 || Per-Line<br />
|- <br />
| rollhilightlineheight || Determines the height of the hilight box placed around roll results ('''''1.4.2+''''') || 1.0em || Per-Line<br />
|-<br />
| roundUp || If set to a non-default value, integer division will round up instead of down || 0 || Per-Line<br />
|-<br />
| showfromfornonwhispers || If set to a non-zero value, will include the sender on cards that aren't whispered || 0 || Global<br />
|-<br />
| 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<br />
|-<br />
| subtitleFontColor || Color of the text in the subtitle areas || #FFFFFF || Global<br />
|-<br />
| subtitleFontFace || Name of the font used on the subtitle sections || Tahoma || Global<br />
|-<br />
| subtitleFontSize || Size of the subtitle font || 13px || Global<br />
|-<br />
| subtitleSeperator || The character(s) that will be placed between leftsub and rightsub || <nowiki>&#x2666</nowiki>; || Global<br />
|-<br />
| tableBorderRadius || CSS specifier for how rounded the borders of the output card are. Use "0px;" for square borders || 6px; || Global<br />
|-<br />
| tableShadow || CSS specifier for the drop shadow under the output card || 5px 3px 3px 0px #aaa; || Global<br />
|-<br />
| tablebgcolor || Background color of the whole card. '''''Normally not visible''''' || #EEEEEE || Global<br />
|-<br />
| tableborder || Color of the border that surrounds the whole card || 2px solid #000000; || Global<br />
|-<br />
| 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<br />
|-<br />
| timezone || IANA Specifier for the local time zone, used in system/date functions || America/New_York || Per-Line<br />
|-<br />
| title || Text displayed in the title area of the card || ScriptCards || Global<br />
|-<br />
| titleCardBackground || A hex color code representing the background color of the title area. || #1c6ea4 || Global<br />
|-<br />
| titleFontColor || Color of the text on the card title || #FFFFFF || Global<br />
|-<br />
| titleFontFace || Name of the font used on the title area || Contrail One || Global<br />
|-<br />
| titleFontLineHeight || Line spacing on the title area || 1.2em || Global<br />
|-<br />
| titleFontSize || Size of the title font || 1.2em || Global<br />
|-<br />
| titlecardbackgroundimage || Specify an image (content for a CSS background-image tag) for the title card area || none || Global<br />
|-<br />
| titlecardbottomborder || Border CSS specifier for the bottom of the title card area || 2px solid #444444; || Global<br />
|-<br />
| titlecardgradient || If set to non-zero value, will place a vertical gradient on the title card area || 0 || Global<br />
|-<br />
| usehollowdice || If set to a non-zero value, the hollow/outline versions of the dice fonts will be used || 0 || Per-Line<br />
|-<br />
| whisper|| Comma separated list of who to whisper the output to. Use "gm" for [[GM|GMs]] and "self" for the sender || none || Global|}<br />
|}<br />
<br />
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). <br />
<br />
''Setting Lines do not produce output lines on the card''<br />
<br />
=== Direct Output (--+) ===<br />
<br />
A direct output line display 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.<br />
<br />
Examples of Direct Output lines:<br />
<pre><br />
--+Hello|World<br />
--+Attack|The monster rolls [$Attack] to hit!<br />
--+Damage|@{target|token_name} is hit for [$Damage] [#3333AA][b]frost[/b][/#] damage.<br />
</pre><br />
<br />
Direct Output lines support inline formatting, roll variable replacement, character attribute references, and procedure variables.<br />
<br />
=== GM Output (--*) ===<br />
<br />
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. <br />
<br />
Example:<br />
<pre><br />
--+PlayerLine|This line is shown on the public card<br />
--*GMLine|This line will only be shown to GMs, on a separate card.<br />
</pre><br />
<br />
=== Roll Variable Assignment (--=) ===<br />
<br />
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.<br />
<br />
'''''All components of a roll equation should be separated with spaces.'''''<br />
<br />
Examples:<br />
<pre><br />
--=MissileDamage|1d4 + 1<br />
--=Attack|1d20 + @{selected|strength_mod} [STR] + @{selected|pb} [PROF]<br />
</pre><br />
<br />
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. Text enclosed in square brackets ([]) is considered "flavor text" and will be added to the result text but does not impact the roll result.<br />
<br />
The following dice formats are supported:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Format Pattern !! Example !! Description<br />
|-<br />
| XdY || 3d8 || Simple format. Roll a Y-sided die X times<br />
|-<br />
| XdYkhZ || 2d20kh1 || Roll Y-sided die X times and keep the highest Z number of dice<br />
|-<br />
| XdYklZ || 4d6kl3 || Roll Y-sided die X times and keep the lowest Z number of dice <br />
|-<br />
| XdY>Z || 5d6>3 || Roll Y-sided die X times and count a 1 for each roll greater than Z <br />
|-<br />
| XdY<Z || 5d6<3 || Roll Y-sided die X times and count a 1 for each roll less than Z <br />
|-<br />
| 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<br />
|-<br />
| 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<br />
|-<br />
| 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)<br />
|-<br />
| 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<br />
|-<br />
| 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).<br />
|-<br />
| 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.<br />
|-<br />
| 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. ('''''v1.5.1''''')<br />
|}<br />
<br />
The following operators are supported in a roll equation:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Operator !! Operation<br />
|-<br />
| + || Addition <br />
|-<br />
| - || Subtraction <br />
|-<br />
| * || Multiplication <br />
|-<br />
| / || Division <br />
|-<br />
| \ || Integer Division (Rounds down) <br />
|-<br />
| % || Modulo (Remainder of Divison)<br />
|}<br />
<br />
Roll Variables can be accessed at any time after they have been created by using the [$VariableName] format, with the following optional modifiers:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Modifier !! Meaning<br />
|-<br />
| No modifier || In a Direct Output Line (<nowiki>--+</nowiki>) 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<br />
|-<br />
| .Total || The end result of the roll equation as an unformatted number <br />
|-<br />
| .Base || The cumulative result of any dice rolled in the Roll Text (Numeric modifiers are not included) <br />
|-<br />
| .Ones || The number of dice in the roll that came up as 1s <br />
|-<br />
| .Aces || The number of dice in the roll that came up as the maximum number on the die <br />
|-<br />
| .Odds || The number of dice in the roll that came up with an odd number <br />
|-<br />
| .Evens || The number of dice in the roll that came up with an even number <br />
|-<br />
| .RollText || The raw text of the roll that was use to generate the results <br />
|-<br />
| .Text || A text representation of the results of the roll, including the numbers rolled for each die <br />
|-<br />
| .tableEntryText || The text portion of the result of a table roll<br />
|-<br />
| .tableEntryImgURL || The image source portion of the result of a table roll<br />
|-<br />
| .tableEntryValue || Numeric value of tableEntryText (via parseInt). If a non-numeric value, will be 0<br />
|-<br />
| .Raw || The total numeric result without any formatting, even if placed somewhere formatting would normally be done. <br />
|}<br />
<br />
Examples:<br />
<pre><br />
--+Total Damage|[$MissileDamage.Total] (roll was 1d4+1)<br />
--+Base Damage|[$MissileDamage.Base] (without the +1)<br />
--=Attack|1d20 + @{selected|strength_mod} [STR] + @{selected|pb} [PROF] + [$BlessBonus] [Bless]<br />
</pre><br />
<br />
In this case, 1d4 will be rolled and stored in “BlessBonus”, which can then be used in the Attack line.<br />
<br />
'''''Mathematical Functions in Roll Expressions '''''<br />
<br />
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:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Expression !! Meaning<br />
|-<br />
| {ABS} || Absolute Value<br />
|-<br />
| {CEIL} || Ceiling value (round up to the next whole number)<br />
|-<br />
| {FLOOR} || Floor value (round down to the next whole number)<br />
|-<br />
| {ROUND} || Round value (round up if the decimal portion is greater than 0.5, otherwise round down) '''Note: As of 1.4.11, ROUND now supports :X as a suffix to round to a given number of decimal places (ie, {ROUND:2}'''<br />
|-<br />
| {NEGATE} || Multiply the value by negative one.<br />
|-<br />
| {SQRT} || Take the square root of the running value.<br />
|-<br />
| {SQUARE} || Square the running value.<br />
|-<br />
| {CUBEROOT} || Take the cube root of the running value.<br />
|-<br />
| {CUBE} || Cube the running value.<br />
|-<br />
| {SIN} || Return the SIN of running value.<br />
|-<br />
| {COS} || Return the COS of running value.<br />
|-<br />
| {TAN} || Return the TAN of running value.<br />
|-<br />
| {ASIN} || Return the ASIN of running value.<br />
|-<br />
| {ACOS} || Return the ACOS of running value.<br />
|-<br />
| {ATAN} || Return the ATAN of running value.<br />
|-<br />
| {MAX:X} || Caps the running value at X. ('''''v1.4.12''''')<br />
|-<br />
| {MIN:X} || If the running value is less than X, set the value to X. ('''''v1.4.12''''')<br />
|-<br />
| {CLAMP:X:Y} || Adjust the running value to remain between X (lower bound) and Y (upper bound) ('''''v1.4.12''''')<br />
|}<br />
<br />
Here are the syntax rules when using the above listed functions:<br />
<br />
Example 1.<br />
<br />
<pre><br />
!script {{<br />
--=output|2.9 {FLOOR}<br />
--+output|[$output]<br />
}}<br />
</pre><br />
<br />
The output from this example is "2".<br />
<br />
Example 2.<br />
<br />
<pre><br />
!script {{<br />
--=output|2.9 {FLOOR} {NEGATE} - 3<br />
--+output|[$output]<br />
}}<br />
</pre><br />
<br />
The output from this example is "-5".<br />
<br />
Basically, a function will use as its input whatever the current "running total" is.<br />
<br />
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.<br />
<br />
<br />
'''''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 <nowiki>[[ ]]</nowiki> 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.<br />
<br />
'''''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.<br />
<br />
'''Rolling on Rollable Tables'''<br />
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.<br />
<br />
''Roll Variable Lines do not produce output lines on the card.''<br />
<br />
=== String Variable Assignment (--&) ===<br />
<br />
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:<br />
<br />
<pre><br />
--&MyText|Hello<br />
</pre><br />
<br />
Here, we assign the text "Hello" to the string variable named MyText. You can also append text to a string variable by prefixing the content with a + sign:<br />
<br />
<pre><br />
--&MyText|+ World<br />
</pre><br />
<br />
If run after the statement above, MyText will now contain "Hello World".<br />
<br />
String variables can be referenced using the syntax [&variablename]<br />
<br />
=== Call API (--@) ===<br />
<br />
ScriptCards can use a Call API instruction to execute other API commands. The Tag contains the API 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 API command is executed.<br />
<br />
Examples:<br />
<pre><br />
--@eh|list<br />
--@alter|_target|@{target|token_id} _bar|3 _amount|-[$Damage]<br />
</pre><br />
<br />
In the first example above, the command <code>!eh list</code> will be executed, calling [[EncounterHelper]]. In the second, {{fpl|1216260/ AlterBars}} is called to modify a token's Bar 3 value.<br />
<br />
'''''Note:''''' When ScriptCards (or any API script) runs other API 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).<br />
<br />
See [[API:Script Index]] for more options.<br />
<br />
=== Branch Label (--:) ===<br />
<br />
A branch label defines a line in your code that can be reached by one of the branching instructions (<nowiki>--^</nowiki>, <nowiki>--></nowiki>, or <nowiki>--?</nowiki>). The Tag serves as the label name, and must be unique on the card.<br />
<br />
The vertical bar (|) separator must be present, but the content portion of the line is unused and can be treated as a comment.<br />
<br />
Examples:<br />
<pre><br />
--:MyLoop|<br />
--:CriticalHit|Will jump here if we roll a critical hit!<br />
</pre><br />
<br />
''A Branch Label line does not produce an output line on the card.''<br />
<br />
=== Branch (--^) === <br />
<br />
A Branch line 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.<br />
<br />
Examples:<br />
<pre><br />
--^MyLoop|Jumps to MyLoop<br />
--^SkipCrit|We didn't crit, so skip the Crit code<br />
</pre><br />
<br />
''A Branch line does not produce an output line on the card.''<br />
<br />
=== Call Procedure (-->) ===<br />
<br />
Similar to a branch, a Call Procedure (sometimes knows 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 (<nowiki>--<</nowiki>) 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 (;).<br />
<br />
Examples:<br />
<pre><br />
-->FixFormat|#3333FF;#999999<br />
</pre><br />
<br />
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%].<br />
<br />
=== Return (--<) ===<br />
<br />
A return instruction marks the end of a Gosub procedure. 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.<br />
<br />
Examples:<br />
<pre><br />
--<|<br />
--<|End of MySub<br />
</pre><br />
<br />
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.<br />
<br />
=== Conditional Statement (--?) ===<br />
<br />
A conditional statement contains some equation in the Tag that will be evaluated. '''''If any part of the comparison can/does contain a space, it needs to be surrounded by double quotes'''''<br />
<br />
Based on the true/false result of the evaluation, one of two execution paths will be taken. These execution paths are detailed in the content section of the statement. The "if true" path is specified first (directly after the vertical bar), and the "if false" path is specified after it, also separated by a vertical bar.<br />
<br />
Example:<br />
<pre><br />
--?[$AttackRoll.Total] -ge [$TargetAC]|Hit|Miss<br />
</pre><br />
<br />
'''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.'''<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Branch Format !! Meaning<br />
|-<br />
| Label || If just a label is specified, execution will branch to that label when the comparison is matched.<br />
|-<br />
| >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 <br />
|-<br />
| =VariableName || The roll variable "VariableName" will be assigned the value following a semicolon (for example, the code "=Roll;1d20" will assign the value "1d20" to a variable named "Roll", if the condition is true).<br />
|-<br />
| &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).<br />
|-<br />
| % or %! || The current for...next loop will perform the "next" action (%) or will break out (%!) <br />
|-<br />
| [ || Code block (see below)<br />
|}<br />
<br />
Examples:<br />
<pre><br />
--?[$AttackRoll.Base] -eq 20|CriticalHit<br />
--?[$AttackRoll.Base] -eq 1|>Fumble;@{selected|dexterity_mod}<br />
--?"@{target|npc_type}" -inc "undead"|&MonsterType;Undead|&MonsterType;Not Undead<br />
--?[$Attack.Total] >= [$ArmorClass]|>Hit|>Miss<br />
</pre><br />
<br />
In the first example, if the Base value of AttackRoll is a 20 (natural 20 on the die) execution will branch to the CriticalHit label.<br />
<br />
In the second example, 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%].<br />
<br />
The third example looks for the word "undead" in the npc_type attribute of the targeted character. If it exists in the text, the MonsterType string variable will be set to "Undead", otherwise it will be set to "Not Undead". <br />
<br />
The final example would call 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.<br />
<br />
''Text that does/may contain a space should be enclosed in double quotes.''<br />
<br />
The following comparison operators are available:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Comparator !! Meaning<br />
|-<br />
| -eq || Equal To <br />
|-<br />
| -eqi || Case insensitive Equal To <br />
|-<br />
| -ne || Not Equal To <br />
|-<br />
| -nei || Case insensitive Not Equal To <br />
|-<br />
| -gt || Greater Than <br />
|-<br />
| -ge || Greater Than or Equal To <br />
|-<br />
| -lt || Less Than <br />
|-<br />
| -le || Less Than or Equal To <br />
|-<br />
| -inc || Includes (text strings). <br />
|-<br />
| -ninc || Does Not Include (text strings). <br />
|}<br />
<br />
Multi-part conditionals are supported with -and and -or as separators. For example:<br />
<br />
<pre><br />
--?[$Attack.Total] -ge @{target|npc_ac} -and [$Attack.Base] -ne 20|HitButNotCrit<br />
</pre><br />
<br />
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):<br />
<br />
true AND false OR true<br />
<br />
Will be evaluated as true. The first two (true and false) will be false, but then false OR true will be true.<br />
<br />
Conversely:<br />
<br />
true or false and false<br />
<br />
Will be false, because the first true and false will evaluate to true, and then true and false will be false.<br />
<br />
'''CODE BLOCKS'''<br />
<br />
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.<br />
<br />
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:<br />
<br />
<pre><br />
!script {{<br />
--=Roll|1d2<br />
--+Roll|[$Roll]<br />
--?[$Roll.Total] -eq 2|[<br />
--&Value|Yep!<br />
--+|We are inside the TRUE portion of the block<br />
--]|[<br />
--&Value|Nope<br />
--+|We are inside the FALSE portion of the block<br />
--]|<br />
--+After|the blocks!<br />
--+Value|[&Value]<br />
}}<br />
</pre><br />
<br />
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 --]|. <br />
<br />
At this time, blocks cannot be nested, and can only be created as part of a conditional (--[ is not a valid statement type)<br />
<br />
''A conditional statement does not produce a line of output on the card.''<br />
<br />
=== Case Statement (--c) ===<br />
<br />
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:<br />
<br />
<pre><br />
!script {{<br />
--#title|Case Statement Testing<br />
--=Roll|1d4<br />
--C[$Roll.Total]|1:>One;[$Roll]|2:>Two;[$Roll]|3:>Three;[$Roll]|4:>Four;[$Roll]<br />
--X|<br />
<br />
--:One| --+Value|was One ([%1%]) --<|<br />
--:Two| --+Value|was Two ([%1%]) --<|<br />
--:Three| --+Value|was Three ([%1%]) --<|<br />
--:Four| --+Value|was Four ([%1%]) --<|<br />
}}<br />
</pre><br />
<br />
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 variable as a parameter.<br />
<br />
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:<br />
<br />
<pre>--c?{Difficulty|10|20|30|40}|10:=BonusHealing;0|20:=BonusHealing;10|30:=BonusHealing;30|40:=BonusHealing;50</pre><br />
<br />
The $BonusHealing variable will then contain either 0, 10, 30, or 50 depending upon the user's choice.<br />
<br />
Using this syntax, the first example in this section could be rewritten as:<br />
<br />
<pre><br />
!script {{<br />
--#title|Case Statement Testing<br />
--=Roll|1d4<br />
--C[$Roll.Total]|1:&Result;One|2:&Result;Two|3:&Result;Three|4:&Result;Four<br />
--+Value|was [&Result] ([$Roll.Raw])<br />
}}<br />
</pre><br />
<br />
Instead of branching, this 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.<br />
<br />
=== Save and Load (--s and --l) ===<br />
<br />
This statement pair is used to either store (--s) or load (--l) data from persistent storage. Items stored in persistent storage remain between card rolls and between Roll20 sessions. There are two types of data that can be stored: settings and roll variables. <br />
<br />
Examples:<br />
<br />
<pre><br />
--Ssettings|GreenStyle<br />
--Srollvariables|FirstCardVars<br />
</pre><br />
<br />
In this case, the tag for the statement determines what type of item is being saved (settings or rollvariables). When saving settings, all non-default settings are written to the named setting storage value. When Roll Variables are saved, all variables that currently exist will be saved to the named storage value.<br />
<br />
Loading stored items simply requires the same command with the --l statement type:<br />
<br />
<pre><br />
--Lsettings|GreenStyle<br />
--Lrollvariables|FirstCardVars<br />
</pre><br />
<br />
When loading settings, all stored settings will be applied to the current card settings. You can override settings by changing them after the load.<br />
<br />
When loading roll variables, the saved variables will be added to (or overwrite if they have the same name) any variables on the current card. This means it is safe to create roll variables before the load statement.<br />
<br />
'''Practical Uses'''<br />
The major intended use of persistent storage is for storing card formats for use in later scripts. For example, the following script:<br />
<br />
<pre><br />
!scriptcard {{<br />
--#titlecardbackground|#22CC22<br />
--#oddrowbackground|#cceecc<br />
--#evenrowbackground|#99ee99<br />
--Ssettings|@{selected|token_name}<br />
}}<br />
</pre><br />
<br />
Would save the titlecardbackground, oddrowbackground, and evenrowbackground settings to a saved list named after the selected token's name. When creating cards for that token to run later, you could include the line:<br />
<br />
<pre><br />
--Lsettings|@{selected|token_name}<br />
</pre><br />
<br />
To load all of the settings at once. By creating these setting sets for each character, you can specify a different color scheme for each character that can then be used in cards with a single formatting line.<br />
<br />
There is a supplemental ! command added to support saved settings:<br />
<br />
<pre><br />
!sc-liststoredsettings<br />
</pre><br />
<br />
Will produce a list of all stored setting names, with buttons to list the setting values stored in each group and a button to delete groups as needed.<br />
<br />
=== Visual Effects (--v) ===<br />
<br />
The --v statement can be used to create visual effects on the tabletop. The tag portion of the statement can be either "token" or "betweentokens". The content portion of the statement contains the required parameters for the effect generation, separated by spaces. If the effect is "none", no effect will be played. If any other value that doesn't match a Roll20 effect name will result in a burst-fire effect.<br />
<br />
For "token" effects, the parameters are the token id for the token the effect happens on, followed by the effect specifier.<br />
<br />
Example:<br />
<pre><br />
--vtoken|@{selected|token_id} burst-fire<br />
</pre><br />
<br />
For "betweentoken" effects, the parameters are the source token id, the target token id, and the effect specifier.<br />
<br />
Example:<br />
<pre><br />
--vbetweentokens|@{selected|token_id} @{target|token_id} beam-magic<br />
</pre><br />
<br />
'''''Version 1.2.8+'''''<br />
<br />
An additional effect specifier, "point" is available in 1.2.8+. This specifier allows you to create a visual effect at a designated X/Y pixel coordinate. Future updates will add custom-vfx support to this option. The parameters are the X and Y coordinates and the effect descriptor. As of version 1.2.9, you can also use custom effect specifiers with Point effects:<br />
<br />
<pre><br />
--vpoint|150 200 burst-fire<br />
</pre><br />
<br />
=== Audio Effects (--a) ===<br />
<br />
'''''Requires version 1.5.2+'''''<br />
<br />
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.<br />
<br />
<pre><br />
--a|SwordHitSound<br />
</pre><br />
<br />
No external APIs are required.<br />
<br />
=== Echo to Chat (--e) ===<br />
<br />
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.<br />
<br />
Example:<br />
<pre><br />
--eThe Ghost|/em hovers around @{selected|character_name}... BOO!<br />
</pre><br />
<br />
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).<br />
<br />
'''''Whispering'''''<br />
<br />
You can use the echo statement to send a whisper, but there's a trick to it. If you execute this code here:<br />
<br />
<pre><br />
--eThe Ghost|/w ExamplePlayerName Boo.<br />
</pre><br />
<br />
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.<br />
<br />
So, in conclusion, it's best to use something like this when you're sending a whisper:<br />
<br />
<pre><br />
!script {{<br />
--#hidecard|1<br />
--&sender|The Ghost<br />
--&receiver|ExamplePlayerName<br />
--&message|Boo.<br />
--e[&sender]|/w [&receiver] [&message]<br />
--eScriptCards|/w gm **Whispered from [&sender] to [&receiver]:** [&message] <br />
}}<br />
</pre><br />
<br />
This will ensure that the message appears in your chat feed as well.<br />
<br />
=== Repeating Section Access (--R) ===<br />
<br />
ScriptCards supports accessing [[Repeating Section]] rows on a character sheet (for example: the attacks, the items, and the repeating resources) with the {{c|--R}} statement type. <br />
<br />
There are three basic commands you can use with --R, and they are specified by <br />
the tag used:<br />
<br />
<br />
'''''The "find" tag'''''<br />
<br />
An Rfind statement is used to search through a repeating field. Here is the general form of such a statement.<br />
<br />
<pre><br />
--Rfind|characterid;EntryName;SectionPrefix;SearchField<br />
</pre><br />
<br />
This is the most direct way to access a repeating section row. Supplying the character ID, followed by what you are looking for (Greatsword, for example), followed by the character sheet's section prefix ({{c|repeating_attack}}), followed by the field to check what you are searching for ({{c|atkname}}) will load the matching section (if found) into the script parsers memory. For example:<br />
<br />
<pre><br />
--Rfind|@{selected|character_id};Greatsword;repeating_attack;atkname<br />
</pre><br />
<br />
Will look at the character's {{c|repeating_attack}} section for an entry with an {{c|atkname}} value equal to "Greatsword". Similarly:<br />
<br />
<pre><br />
--Rfind|@{selected|character_id};Bite;repeating_npcaction;name<br />
</pre><br />
<br />
Will look for a "Bite" action on an NPC's action list.<br />
<br />
<br />
'''''The "first" tag'''''<br />
<br />
<pre><br />
--Rfirst|characterid;section prefix<br />
</pre><br />
<br />
This form of the --R command will look at all of the entries in the specified repeating section and load the first one into memory:<br />
<br />
<pre><br />
--Rfirst|@{selected|character_id};repeating_attack<br />
</pre><br />
<br />
Would load the character's first "repeating_attack" row into memory.<br />
<br />
<br />
'''''The "next" tag'''''<br />
<br />
<pre><br />
--Rnext|<br />
</pre><br />
<br />
No parameters are required for --Rnext, which loads the next entry in the list that was obtained with "first" into memory.<br />
<br />
<br />
'''''Section prefixes and how to use them'''''<br />
<br />
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 open [[D&D 5E by Roll20|this page]], and search for the phrase "repeating sections".<br />
<br />
<br />
'''''Additional information'''''<br />
<br />
However a row is obtained, it will be parsed to replace any attribute references (ie, <code>@{level}</code>) with the corresponding character attribute.<br />
<br />
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".<br />
<br />
You can reference repeating attribute data using the syntax {{c|[*R:attributename]}} syntax (similar to referencing standard character attributes).<br />
<br />
Here are some examples:<br />
<br />
Display the details of the "Greatsword" PC attack:<br />
<br />
<pre><br />
!script {{<br />
--Rfind|@{selected|character_id};Greatsword;repeating_attack;atkname<br />
--+Attack Name|[*R:atkname]<br />
--+Base Damage|[*R:dmgbase]<br />
}}<br />
</pre><br />
<br />
[[File:Scriptcards repeating greatsword.png|Repeating Greatsword Attack]]<br />
<br />
List all of the actions an NPC can take (just actions, not legendary, etc.)<br />
<br />
<pre><br />
!script {{<br />
--#title|NPC Actions<br />
--#leftsub|@{selected|token_name}<br />
--Rfirst|@{selected|character_id};repeating_npcaction<br />
--:DisplayLoop|<br />
--?"[*R:name]" -eq NoRepeatingAttributeLoaded|Done<br />
--+Action:|[*R:name] [*R:attack_damage] [*R:attack_damagetype]<br />
--?"[*R:attack_damage2]" -eq ""|NoSecondaryDamage<br />
--+ |[*R:attack_damage2] [*R:attack_damagetype2]<br />
--:NoSecondaryDamage|<br />
--Rnext|<br />
-->DisplayLoop| <br />
--:Done|<br />
}}<br />
</pre><br />
<br />
[[File:Scriptcards repeating npcactions.png]]<br />
<br />
In the script above, we get the "first" repeating_npcaction and display information about it. We then execute "next" and repeat until we run into "NoRepeatingAttributeLoaded".<br />
<br />
See the section named [[#Repeating Section Values|Repeating Section Values]] for more information.<br />
<br />
<br />
'''''Special debugging command: dump'''''<br />
<pre><br />
--Rdump|<br />
</pre><br />
<br />
The "dump" command will list all of the attributes ScriptCards knows about for the currently loaded repeating row to the [[API Console]] Log.<br />
<br />
=== Assign Variable to Built-In Function (--~) ===<br />
<br />
ScriptCards has the ability to run a function built into the API script and return the results to a variable. Some functions return roll variables, while others return strings. See the function table below for details. The format is:<br />
<br />
<pre>--~VariableName|function;param1;param2;param3;...</Pre><br />
<br />
::{| class="wikitable"<br />
|-<br />
! Function Name !! Parameters !! Description<br />
|-<br />
| distance || token_A_ID;token_B_ID || Calculate the Chebyshev distance in grid units between two tokens. This is the measurement scheme D&D 4E/5E use for diagonal distance measurement<br />
|-<br />
| euclideandistance || token_A_ID;token_B_ID || Calculate the Euclidean distance between two tokens. This is essentially the Pythagorean theorem in action. Returns the result in grid units.<br />
|-<br />
| euclideanpixel || token_A_ID;token_B_ID || Calculate the Euclidean distance between two tokens and returns the result is pixels instead of grid units. <br />
|-<br />
| euclideanlong || token_A_ID;token_B_ID || 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 is calculated instead of before. More accurate over long distances. <br />
|-<br />
| manhattandistance || token_A_ID;token_B_ID || Also called "taxicabdistance" (which is an acceptable function name), this measures to how-many-over, how-many-up/down distance, disallowing diagonal movement.<br />
|-<br />
| getselected || none || 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 the first selected token, VariableName2 the second, etc.<br />
|}<br />
<br />
'''''Functions with Sub Functions'''''<br />
<br />
Most ScriptCards functions are grouped into set as sub functions. The table below lists the major functions and their sub functions.<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Function Name !! Sub Function !! Parameters !! Return Type !! Description<br />
|-<br />
| array || define || arrayname;value1;value2;... || none || Creates an array called "arrayname" and adds value1, value2, etc. to the array<br />
|-<br />
| array || sort || arrayname || none || Sorts the specified array in place in ascending order (alphabetically)<br />
|-<br />
| array || numericsort || arrayname || none || Sorts the specified array in place in ascending order (numerically) ('''''v 1.4.10+ ''''')<br />
|-<br />
| array || add || arrayname;value1;value2;... || none || Adds value1, value2, ... to the existing array "arrayname"<br />
|-<br />
| array || remove || arrayname;value1;value2;... || none || Removes value1, value2, ... from the existing array "arrayname". Resets the array index to 0.<br />
|-<br />
| array || replace || arrayname;currentvalue;newvalue || none || Replaces all occurrences of "currentvalue" in "arrayname" with "newvalue"<br />
|-<br />
| array || setatindex || arrayname;index;newvalue || none || Replaces the array item at index "index" with "newvalue"<br />
|-<br />
| array || getindex || arrayname || stringVariable || Retrieves the current index in "arrayname" and stores it in the supplied string variable<br />
|-<br />
| array || setindex || arrayname;newindex || none || Sets the current index in array "arrayname" to "newindex"<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| array || removeat || arrayname;indexposition || none || Removes the item at index "indexposition" from "arrayname". Resets the current array index to 0.<br />
|-<br />
| array || indexof || arrayname;searchvalue || stringVariable || Searches the array "arrayname" for and item with the value of "searchvalue" and, if found, returns the index of the first matching value or "ArrayError" if not found<br />
|-<br />
| array || getlength || arrayname || stringVariable || Returns the number of items in array "arrayname"<br />
|-<br />
| array || pagetokens || arrayname;tokenid;(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. 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.)<br />
|-<br />
| 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.<br />
|-<br />
| array || stringify || arrayname || stringVariable || Returns all of the items in "arrayname" as a string separated by semicolons (;)<br />
|-<br />
| array || fromstring || arrayname;delimiter;string || unused || Creates an array from "string", splitting "string" on "delimiter" to separate the items<br />
|-<br />
| array || statusmarkers|| arrayname;tokenid || none|| Creates an array (arrayname) of the active statusmarkers (sometimes called Token Markers) for the specified tokenid<br />
|-<br />
| math || angle || math;angle;tokenid;tokenid|| rollVariable || Calculates the angle between two tokens and returns the value in degrees<br />
|-<br />
| math || ceil || math;ceil;value || rollVariable || Rounds '''value''' up to the next integer, dropping any decimal portion of the number<br />
|-<br />
| math || clamp || math;clamp;value;lowerBound;upperBound || rollVariable || Returns '''value''', but restricted to the range of '''lowerBound''' and '''upperBound'''.<br />
|-<br />
| math || floor || math;floor;value || rollVariable || Rounds '''value''' down, dropping any decimal portion of the number<br />
|-<br />
| math || max || math;max;valueA;valueB || rollVariable || Returns the larger of '''valueA''' vs '''valueB'''<br />
|-<br />
| math || min || math;min;valueA;valueB || rollVariable || Returns the smaller of '''valueA''' vs '''valueB'''<br />
|-<br />
| math || round || math;round;value || rollVariable || Rounds '''value''' to the nearest integer<br />
|-<br />
| string || length || string;length;stringValue || rollVariable || Returns the length of '''stringValue''' in characters<br />
|-<br />
| string || before || string;before;searchText;stringValue || stringVariable || Searches '''stringValue''' for '''searchText''' and returns the portion of '''stringValue''' prior to that text<br />
|-<br />
| string || after || string;after;searchText;stringValue || stringVariable || Searches '''stringValue''' for '''searchText''' and returns the portion of '''stringValue''' after that text<br />
|-<br />
| string || left || string;left;count;stringValue || stringVariable || Returns the leftmost '''count''' characters of '''stringValue'''<br />
|-<br />
| string || right || string;right;count;stringValue || stringVariable || Returns the rightmost '''count''' characters of '''stringValue'''<br />
|-<br />
| string || replace || string;replace;searchText;replaceText;stringValue || stringVariable || Replaces '''searchText''' in '''stringValue''' with '''replaceText''' and returns the resulting string<br />
|-<br />
| 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+'''''<br />
|-<br />
| string || trim || string;trim;stringValue || stringVariable || Removes leading and trailing spaces from stringValue and returns the result. <br />
|-<br />
| string || substring || string;substring;start;count;stringValue || stringVariable || Returns '''count''' characters starting at '''start''' from '''stringValue'''<br />
|-<br />
| 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.<br />
|-<br />
| string || tolowercase || string;tolowercase;stringValue || stringVariable || Converts the passed string to lower case and assigns to the passed variable name. <br />
|-<br />
| string || touppercase || string || stringVariable || Converts the passed string to upper case and assigns to the passed variable name. <br />
|-<br />
| 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. <br />
|-<br />
| 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.<br />
|-<br />
| 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'''.<br />
|-<br />
| turnorder || clear || none || none || Clears all entries from the {{Turn Tracker}}/Initiative<br />
|-<br />
| turnorder || addtoken || tokenid;trackervalue || none || Adds the token represented by "tokenid" to the initiative tracker with an initiavie value of "trackervalue"<br />
|-<br />
| turnorder || replacetoken || tokenid;trackervalue || none || Replaces the token represented by "tokenid" in the initiative tracker with an initiavie value of "trackervalue". Will add the token if it doesn't exist in the tracker.<br />
|-<br />
| turnorder || removetoken || tokenid || none || Removes the token represented by "tokenid" from the initiative tracker if it exists<br />
|-<br />
| turnorder || addcustom || textlabel;trackervalue || none || Add a custom text entry to the {{Turn Tracker}}/Initiative named "textlabel" with an initiative value of "trackervalue"<br />
|-<br />
| system || date || getdatetime || stringVariable || Returns the date time in the active timezone (see settings) <br />
|-<br />
| system || date || getdate || stringVariable || Returns the date in the active timezone (see settings) <br />
|-<br />
| system || date || gettime || stringVariable || Returns the time in the active timezone (see settings)<br />
|-<br />
| system || dumpvariables || "rolls", "string", or "array" || none || Dumps all of the defined variables of the indicated type to the console log<br />
|-<br />
| system || findability || system;findability;charactername;abilityname || stringVariable || Returns the object ID of the ability on the indicated character or "AbilityNotFound"<br />
|-<br />
|}<br />
<br />
Examples:<br />
<br />
<pre><br />
--~HowFarAway|distance;@{selected|token_id};@{target|token_id}<br />
</pre><br />
<br />
Returns the distance (Chebyshev) between the selected and target tokens and stores it in "HowFarAway".<br />
<br />
<pre><br />
--SelectedDudes|getselected<br />
</pre><br />
<br />
If 5 tokens were selected, 6 variables would be created: SelectedDudesCount (with a value of 5), SelectedDudes1, SelectedDudes2, SelectedDudes3, SelectedDudes4, SelectedDudes5.<br />
<br />
=== Information Request (--i) ===<br />
<br />
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.<br />
<br />
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.<br />
<br />
After the user has clicked the button and responded to the requests, ScriptCards will resume processing the script from where it left off.<br />
<br />
Here is an example “i” line:<br />
<br />
<pre><br />
--IScriptCards needs additional information to continue;Click to select a target and provide information|t;MyNewTarget;Missile1Target||q;MyNameIs;What is your name?<br />
</pre><br />
<br />
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.<br />
<br />
Supported information request types are “t” for target token, and “q” for query.<br />
<br />
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).<br />
<br />
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:<br />
<br />
<pre><br />
q;UserName;What is your name?|Fred|Bob|Sally|Nancy<br />
</pre><br />
<br />
Would have a dropdown menu with four choices.<br />
<br />
=== Object Modification (--!) ===<br />
<br />
'''''Requires ScriptCards version 1.5.0+'''''<br />
<br />
Object modification support is now available in ScriptCards. As of 1.5.0, you can use the --! command to modify object properties in the game. This may help reduce the reliance on the --@ command to run other API commands to modify token/character values. The biggest benefit of this is that the changes happen as the script is processing, so the new values are available right away. <br />
<br />
The format of the command is:<br />
<pre><br />
--!<objectType>:<objectId>|setting:value|setting:value|setting:value...<br />
</pre><br />
<br />
'''objectType''' can be one of "t" for token, "c" for character, or "a" for character attribute<br />
<br />
'''objectId''' can be a token id or a character id (or "S"/"T" for the Source/Target token/char defined with --#sourcetoken and --#targettoken)<br />
<br />
'''setting''' and '''value''' pairs can be chained in a single statement separated by | to impact more than one property/attribute with a single line<br />
<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
Examples:<br />
<br />
Set the value of bar1_value for the selected token to 5:<br />
<pre> --!t:@{selected|token_id}|bar1_value:5</pre><br />
Add 1 to the bar3_value for the selected token:<br />
<br />
<pre> --!t:@{selected|token_id}|bar3_value:+=1</pre><br />
Set bar2_value to 5 and bar2_max to 10 for the selected token<br />
<br />
<pre> --!t:@{selected|token_id}|bar2_value:5|bar2_max:10</pre><br />
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:<br />
<br />
<pre> --!a:@{selected|token_id}|dndstyling:on|size:enormous|!attitude:epic</pre><br />
Adds 50 to the npc_xp attribute for the character represented by the selected token, displaying the value before and after the update:<br />
<br />
<pre><br />
!script {{<br />
--+XP|[*@{selected|token_id}:npc_xp]<br />
--!a:@{selected|token_id}|npc_xp:+=50<br />
--+XP|[*@{selected|token_id}:npc_xp]<br />
}}<br />
</pre><br />
<br />
Note that asynchronous read/update fields (bio, notes, gmnotes) are not currently supported.<br />
<br />
== Inline Formatting ==<br />
<br />
Inline formatting is processed on Direct Output lines only (--+ lines) and the following inline format markup is available:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Formatting Tags !! Description<br />
|-<br />
| [b]..[/b] || Bold the text between the markers <br />
|-<br />
| [i]..[/i] || Italicize the text between the markers <br />
|-<br />
| [u]..[/u] || Underline the text between the markers <br />
|-<br />
| [s]..[/s] || Strike-Thru the text between the markers <br />
|-<br />
| [c]..[/c] || Center alignment <br />
|-<br />
| [l]..[/l] || Left alignment <br />
|-<br />
| [r]..[/r] || Right alignment <br />
|-<br />
| [j]..[/j] || Full justification alignment <br />
|-<br />
| [br] || Line break (translates to <pre><br></pre> in html)<br />
|-<br />
| [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<br />
|-<br />
| [#xxx]..[/#] or [#xxxxxx]..[/#] || Use a 3 or 6 digit hex code to colorize the text between the markers <br />
|-<br />
| [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, <code>[img width=128 height=128]</code> )<br />
|-<br />
| [button]caption::action[/button] || Create a button with the label "caption" that performs the action defined by "action". By default, buttons will be colored according the the buttontextcolor and buttonbackground card settings. You can optionally color individual buttons by specifying a text color and a background color as part of the [button] command (ie, [button:#ffffff:#000000] will create a button with white text on a black background. In order to set a background color, the foreground color must be specified.<br />
|-<br />
| [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. By default, buttons will be colored according the the buttontextcolor and buttonbackground card settings. You can optionally color individual buttons by specifying a text color and a background color as part of the [sheetbutton] command (ie, [sheetbutton:#ffffff:#000000] will create a button with white text on a black background. In order to set a background color, the foreground color must be specified.<br />
|-<br />
| [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. By default, buttons will be colored according the the buttontextcolor and buttonbackground card settings. You can optionally color individual buttons by specifying a text color and a background color as part of the [rbutton] command (ie, [rbutton:#ffffff:#000000] will create a button with white text on a black background. In order to set a background color, the foreground color must be specified.<br />
|-<br />
| [t] || Converted to HTML table tag. Text after the "t" will be included inside the tag (width, border, etc)<br />
|-<br />
| [/t] || Converted to HTML close table tag.<br />
|-<br />
| [tr] || Converted to HTML table row tag. Text after the "tr" will be included inside the tag<br />
|-<br />
| [/tr] || Converted to HTML close table row tag.<br />
|-<br />
| [td] || Converted to HTML table cell tag. Text after the "tr" will be included inside the tag<br />
|-<br />
| [/td] || Converted to HTML close table cell tag.<br />
|}<br />
<br />
Code Example<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Formatting Tags !! Description<br />
|-<br />
| <pre>!script {{<br />
--#title|Inline Formatting Examples<br />
--+|This text [b]is bolded[/b]<br />
--+|This text [i]is italicized[/i]<br />
--+|This text [u]is underlined[/u]<br />
--+Alignment|[l]Left[/l]<br />
--+|[c]Center[/c]<br />
--+|[r]Right[/r]<br />
--+|[j]This long bit of text is justified to fit smoothly into the display area for the card with justified wrapping.[/j]<br />
--+Colorized|[#f00]Red[/#] [#0f0]Green[/#] [#00f]Blue[/#]<br />
--+Button|[button]Do Something::DoOnClick[/button]<br />
--+Button Colors|[button:#000:#f00]Red::RedClick[/button] [button:#000:#0f0]Blue::BlueClick[/button] [button:#000:#00f]Blue::BlueClick[/button]<br />
--+Table:|<br />
--+|[t border=2 width=100%][tr][td]Cell1[/td][td]Cell2[/td][/tr][tr][td]Cell3[/td][td]Cell4[/td][/tr][/t]<br />
}}</pre> || [[File:Sc-formatting_example.png]]<br />
|}<br />
<br />
== Variables ==<br />
<br />
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. While it is possible to assign both a string and a roll variable the same name, doing so will likely result in confusion when looking at the script later, so it is not recommended.<br />
<br />
String Variables are assigned with the --& statement and are referenced using [&variableName] notation.<br />
<br />
Roll Variables are assigned with the --= statement, and the assignment value is always processed by the ScriptCards Roll Processor (resolves dice rolls, etc.)<br />
<br />
There are a handful of variables assigned automatically when a ScriptCard is executed. These are all string variables, and are:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Variable !! Value<br />
|-<br />
| SendingPlayerID || Contains the object ID of the player that sent the macro<br />
|-<br />
| SendingPlayerName || Contains the display name of the player<br />
|-<br />
| SendingPlayerColor || Contains the color code associated with the player<br />
|-<br />
| SendingPlayerSpeakingAs || The contents of the "Speaking As" dropdown window<br />
|-<br />
| SendingPlayerIsGM || Contains 1 if the player is a GM, and 0 if the player is NOT a GM<br />
|}<br />
<br />
== Arrays ==<br />
<br />
Arrays are a special type of variable, and are managed by the function (<nowiki>--~</nowiki> command). All of the array function commands follow the same pattern:<br />
<br />
<pre>--~variableName|array;subcommand;arrayname;param1;param2;param3;...</pre><br />
<br />
Not all array commands return anything to "variableName". The function table above will specify the return type of the command if any.<br />
<br />
There are a couple of different ways to create an array:<br />
<br />
The '''define''' array subcommand creates (or recreates) an array and assigns it values - one for each included parameter after the array name. For example:<br />
<br />
<pre>--~|array;define;Fruits;mango;peach;strawberry;apricot;banana;apple</pre><br />
<br />
will create an array called '''Fruits''' with 6 elements in the order listed in the command (mango, peach, etc.)<br />
<br />
You can also use two other subcommands to create arrays based on tokens:<br />
<br />
<pre>--~Count|array;pagetokens;Everybondy;@{selected|token_id}</pre><br />
<br />
and<br />
<br />
<pre>--~Count|array;selectedtokens;Selected</pre><br />
<br />
In both cases, arrays of tokens will be created, and a string variable called "Count" will be set to the number of tokens in the array. The '''pagetokens''' command returns (by default) all of the tokens on the page that contains the token passed as the parameter after the array name. You can filter the tokens that "pagetokens" includes in the array by appending an optional parameter describing the type of token you are looking for:<br />
<br />
<pre>--~Count|array;pagetokens;Everybondy;@{selected|token_id};npc</pre><br />
<br />
Will return only tokens on the page that represent characters that do not have a ''controlledby'' parameter set. The available options are "all" (default), "char", "graphic", "pc", and "npc".<br />
<br />
The '''selectedtokens''' command returns an array with all of the tokens that were selected when the script was called.<br />
<br />
You can also use an arbitrary string to create an array, specifying a delimiter with the '''fromstring''' command:<br />
<br />
<pre><br />
--&names|Fred<br />
--&names|+,Sally<br />
--&names|+,Ted<br />
--&names|+,Joyce<br />
--~|array;fromstring;,;[&names]<br />
</pre><br />
<br />
The above example builds a comma-separated string and then uses "fromstring" to create an array with 4 elements from it, specifying the comma as the delimiter.<br />
<br />
Finally, you can use the '''statusmarkers''' command to create an array with one entry for each active status marker on a specified token:<br />
<br />
<pre>--~|array;statusmarkers;Conditions;@{selected|token_id}</pre><br />
<br />
will create an array with one entry for each status active on the selected token. The array elements will be the internal name of the status (if you are using custom status marker packs, the names will be specified in the marker pack).<br />
<br />
'''Traversing Arrays'''<br />
<br />
Each array keeps track of an internal index position (starting at 0). Several commands let you manage this index:<br />
<br />
*'''getindex''' returns the current index value<br />
*'''setindex''' sets the index to the specified location in the array<br />
*'''getlength''' returns the number of elements in the array<br />
*'''indexof''' returns the index location of the specified element<br />
<br />
Other commands let you retrieve values from the array:<br />
<br />
*'''getfirst''' sets the index to 0 and returns the value at that position<br />
*'''getnext''' advances the index by 1 and returns the new current value<br />
*'''getprevious''' reduces the index by 1 and returns the new current value<br />
*'''getlast''' sets the index to the last elements in the array and returns the new current value<br />
<br />
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.<br />
<br />
'''Manipulating Array Elements'''<br />
<br />
Several array commands deal with inserting, removing, and modifying elements:<br />
<br />
*'''add''' works just like define, except that it takes an existing array and adds elements to it based on the passed parameters<br />
*'''remove''' looks for items matching each passed parameter and removes them from the indicated array if they exist<br />
*'''removeat''' allows you to specify an index location in the array and remove the element at that position<br />
*'''replace''' searches an array for a value and replaces all occurrences of it with a new value (if found)<br />
*'''sort''' sorts the elements in the array in ascending order<br />
*'''strinfigy''' returns a string variable that includes each array element separated by semicolons (;) <br />
<br />
'''Referencing Array Elements'''<br />
<br />
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.<br />
<br />
<pre><br />
!script {{<br />
--~dummy|array;pagetokens;myarray;@{selected|token_id}<br />
--~count|array;getcount;myarray<br />
--+Total:|There are [&count] graphical objects on the page<br />
--~testvar|array;getfirst;myarray<br />
--:loop|<br />
--+Value|[*[&testvar]:character_name]<br />
--~testvar|array;getnext;myarray<br />
--?[&testvar] -ne ArrayError|loop<br />
--+Loop1|Is Done!<br />
}}<br />
</pre><br />
<br />
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:<br />
<br />
<pre><br />
!script {{<br />
--~dummy|array;pagetokens;myarray;@{selected|token_id}<br />
--~count|array;getcount;myarray<br />
--+Total:|There are [&count] graphical objects on the page<br />
--%loopCounter|1;[&count]<br />
--+Value|[*[@myarray([&loopCounter])]:character_name]<br />
--%|<br />
--+Loop|Is Done!<br />
}}<br />
</pre><br />
<br />
This line : <nowiki>--+Value|[*[@myarray([&loopCounter])]:character_name]</nowiki> uses [@arrayName(index)] format (inside a [*characterid:attribute] syntax) to perform the same task as running through the loop with the index.<br />
<br />
(Note: Additional examples are on the way...)<br />
<br />
== For...Next Loops ==<br />
<br />
For...Next loops in ScriptCards are supported with the with the --% statement type. A loop is defined by starting off with:<br />
<br />
<pre><br />
--%LoopCounter|<start>;<end>;[step]<br />
</pre><br />
<br />
The start and end values are required, while the step parameter is optional. If the step is omitted, it will be assumed to be 1. A string variable named after the line tag ("LoopCounter" in the case above) will be created and will hold the current iteration value for the loop. Here is a real example:<br />
<br />
<pre><br />
--%LoopCounter|1;10;1<br />
</pre><br />
<br />
This will begin a loop identified by "LoopCounter" that will start at 1, increasing by 1 each iteration (the step) until it has completed 10 executions.<br />
<br />
The "next" statement is simply <code>--%|</code>, with no tag or parameters. This indicates to ScriptCards that it should increment the counter and go back to the beginning of the loop. Extending the example above:<br />
<br />
<pre><br />
!script {{<br />
--%LoopCounter|1;10;1<br />
--=Roll|1d20<br />
--+Loop|Counter is [&LoopCounter], roll was [$Roll]<br />
--%|<br />
}}<br />
</pre><br />
<br />
The <code>--%!|</code> sequence will break out of the loop, no matter how many iterations are remaining.<br />
<br />
The % and %! character sequences can also be used as part of a 1.2.1+ non-branching conditional to continue or break the loop:<br />
<br />
<pre><br />
--?"X[&RollInto]X" -eq "XX"|%<br />
</pre><br />
<br />
In this example, if the string variable RollInfo is empty, the loop will return to the top and continue with the next iteration, while:<br />
<br />
<pre><br />
--?"X[&RollInto]X" -eq "XX"|%!<br />
</pre><br />
<br />
Would cause the whole loop to end if the condition were true.<br />
<br />
== Referencing ==<br />
<br />
=== Referencing Overview ===<br />
Referencing allows you to substitute the values of variables, objects, attributes, settings, and the like someplace in a ScriptCards line. The table below gives an overview of the various referencing modes and what each one means. In general, references are enclosed in square brackets ({{c|[}} and {{c|]}}) and begin with a character indicating what kind of reference it is (such as {{c|$}} or {{c|&}}), followed by a descriptor that indicates where the value should come from.<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Character !! Type !! Example !! Notes<br />
|-<br />
| $ || Roll Variable || [$AttackRoll] || Roll variables support a number of modifiers (ie, {{c|[$AttackRoll.Base]}}). See the Roll Variables section below for details<br />
|-<br />
| & || String Variable || [&PlayerName] || <br />
|-<br />
| * || Object Attributes || [*S:character_name] || See Attribute Referencing in the next table for details.<br />
|-<br />
| % || Subroutine Parameters || [%1%] || Only available when a subroutine is called with a {{c|-->}} or similar construct. Parameters are numbered beginning at 1.<br />
|-<br />
| @ || Array Elements || [@Colors(5)] || The name of the array follows the {{c|@}} symbol. The index (zero-based) is in parenthesis after the name.<br />
|-<br />
| ~ || Card Settings || [~title] || Returns the value of the ScriptCards settings (set via {{c|--#}} lines)<br />
|}<br />
<br />
''' Object Attribute Referencing '''<br />
<br />
All object attribute referencing use the {{c|*}} prefix character, with the second (and sometimes third) character providing context).<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Prefix !! Example !! Notes<br />
|-<br />
| *S: || [*S:character_name] || Returns token or character attributes for the token/character specified for the {{c|sourcetoken}} setting. Token attributes are prefixed with {{c|t-}} (ex: {{c|[*S:t-bar3_value]}}).<br />
|-<br />
| *T: || [*T:character_name] || Returns token or character attributes for the token/character specified for the {{c|targettoken}} setting. Token attributes are prefixed with {{c|t-}} (ex: {{c|[*T:t-bar3_value]}}).<br />
|-<br />
| *id: || [*-lkfne34mda4:character_name] || when {{c|*}} is followed by an ID, the token/character will be queried for the attribute value requested.<br />
|-<br />
| *C: || [*C:playerpage] || Returns [[campaign]] attributes.<br />
|-<br />
| *P: || [*P:showgrid] || Returns [[Page Settings|page]] attributes. If an {{c|activepage}} setting has been set, the {{c|activepage}} will be referenced. If not, the current {{c|playerpage}} (where the ribbon is) for the campaign is referenced.<br />
|-<br />
| *R: || [*R:atkname] || Used with {{c|--R}} ([[Repeating Section]]) commands to return the VALUE of the current repeating row item's attribute by name.<br />
|-<br />
| *R> || [*R>atkname] || Used with {{c|--R}} (repeating section) commands to return the full attribute name for a repeating row attribute.<br />
|}<br />
<br />
''' Nested References '''<br />
<br />
Reference syntax can be nested, and will be resolved from inside to outside. For example, given a roll variable {{c|MishapRoll}}, and a series of strings ({{c|Mishap1}}, {{c|Mishap2}}, {{c|Mishap3}}, {{c|Mishap4}}), the following reference will begin by substituting {{c|[$MishapRoll.Raw]}} for the roll's numeric value, and then replace the resulting {{c|MishapX}} string with its value:<br />
<br />
<pre>[&Mishap[$MishapRoll.Raw]]</pre><br />
<br />
=== Roll Variables===<br />
<br />
Roll Variables can be referenced from the content portion of any line type, and from the tag portion of conditional statements. The referenced value is replaced when the line is executed.<br />
<br />
There are several modifiers that can be used to reference parts of a roll:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Modifier !! Meaning<br />
|-<br />
| No modifier || In a Direct Output Line (<nowiki>--+</nowiki>), GM Output Line (<nowiki>--*</nowiki>), or String Assignement (<nowiki>--&</nowiki>), 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<br />
|-<br />
| .Total || The end result of the roll equation. Formatting rules for "No Modifier" apply based on line type. <br />
|-<br />
| .Raw || The total value of the roll variable without any formatting, no matter what kind of line the reference is used in.<br />
|-<br />
| .Base || The cumulative result of any dice rolled in the Roll Text (Numeric modifiers are not included) <br />
|-<br />
| .Ones || The number of dice in the roll that came up as 1s <br />
|-<br />
| .Aces || The number of dice in the roll that came up as the maximum number on the die <br />
|-<br />
| .Odds || The number of dice in the roll that came up with an odd number <br />
|-<br />
| .Evens || The number of dice in the roll that came up with an even number <br />
|-<br />
| .RollText || The raw text of the roll that was use to generate the results <br />
|-<br />
| .Text || A text representation of the results of the roll, including the numbers rolled for each die <br />
|-<br />
| .tableEntryText || The text portion of the result of a table roll<br />
|-<br />
| .tableEntryImgURL || The image source portion of the result of a table roll<br />
|-<br />
| .tableEntryValue || If the tableEntryText is purely numeric, will contain the numeric value<br />
|}<br />
<br />
=== String Variables ===<br />
<br />
To reference a string variable, use the notation {{c|[&variablename]}}. String variables can be referenced in direct output, roll variable assignment, and string variable assignment statements.<br />
<br />
=== Character/Token Attributes ===<br />
<br />
A character or token attribute can be referenced from content portion of any type of line and is substituted when the line is executed. The general format for referencing a character attribute is {{c|[*ID:attribute]}}. ID can be a token ID or a character ID (these start with a dash). Additionally if you have specified a sourceToken or targetToken, you can substitute "S" or "T" for the ID (for example {{c|[*S:npc_type]}} will retrieve the {{c|npc_type}} attribute from the source token.<br />
<br />
By default, all attribute references will be pulled from the '''''character''''' object that the ID represents (either directly or by being a Token ID that represents a character).<br />
<br />
Keep in mind, that if you want to access the "max" of a character attribute (for example, the max hit points), then you cannot trust the name that your roll20 character sheet shows you when you hover your mouse over the max hit points. For example, this reference will not work: {{c|[*S:hp_max]}}. Instead, you need to use this reference: {{c|[*S:hp^]}}.<br />
<br />
If your ID refers to a token, token attributes can be accessed by preceding the attribute name with {{c|t-}}, for example {{c|[*S:t-aura1_radius]}}. Supported token attributes are:<br />
'''(NOTE: As of version 1.6.1 of ScriptCards, the below list is no longer a limitation on the token attributes you can reference. All token attributes available in Roll20 can now be accessed and the need to update the internal list as new attributes are added has been eliminated.)'''<br />
<br />
{|<br />
| t-name || t-id || t-statusmarkers || t-bar1_value<br />
|-<br />
| t-bar1_max || t-bar2_value || t-bar2_max || t-bar3_value<br />
|-<br />
| t-bar3_max || t-top || t-left || t-width<br />
|-<br />
| t-height || t-rotation || t-layer || t-aura1_radius<br />
|-<br />
| t-aura1_color || t-aura2_radius || t-aura2_color || t-aura1_square<br />
|-<br />
| t-aura2_square || t-tint_color || t-light_radius || t-light_dimradius<br />
|-<br />
| t-light_angle || t-light_losangle || t-light_multiplier || t-light_otherplayers<br />
|-<br />
| t-light_hassight || t-flipv || t-fliph || t-controlledby<br />
|-<br />
| t-_cardid || t-_pageid || t-imgsrc || t-bar1_link<br />
|-<br />
| t-bar2_link || t-bar3_link || t-represents || t-layer<br />
|-<br />
| t-isdrawing || t-name || t-gmnotes || t-showname<br />
|-<br />
| t-showplayers_name || t-showplayers_bar1 || t-showplayers_bar2 || t-showplayers_bar3<br />
|-<br />
| t-showplayers_aura1 || t-showplayers_aura2 || t-playersedit_name || t-playersedit_bar1<br />
|-<br />
| t-playersedit_bar2 || t-playersedit_bar3 || t-playersedit_aura1 || t-playersedit_aura2<br />
|-<br />
| t-lastmove || t-adv_fow_view_distance || t-has_bright_light_vision || t-has_night_vision<br />
|-<br />
| t-night_vision_distance || t-emits_bright_light || t-bright_light_distance || t-emits_low_light<br />
|-<br />
| t-low_light_distance || t-has_limit_field_of_vision || t-limit_field_of_vision_center || t-limit_field_of_vision_total<br />
|-<br />
| t-has_limit_field_of_night_vision || t-limit_field_of_night_vision_center || t-limit_field_of_night_vision_total || t-has_directional_bright_light<br />
|-<br />
| t-directional_bright_light_center || t-directional_bright_light_total || t-has_directional_dim_light || t-directional_dim_light_center<br />
|-<br />
| t-directional_dim_light_total || t-lightColor || t-tooltip || |<br />
|}<br />
<br />
'''''It is important to note that some attributes names on tokens have corresponding attribute names on characters, which represent different values. For example, {{c|[*T:id]}} returns the character ID, while {{c|[*T:t-id]}} returns the token ID.'''''<br />
<br />
=== Subroutine Parameters ===<br />
<br />
When using a gosub statement (-->) or a conditional marked as a gosub (prefixing the label with a > character), you can pass any number of parameters separated by semicolons (;) that the code in the subroutine can utilize.<br />
<br />
Subroutine parameters are numbered starting at 1, and are accessed by using the notation [%number%], so the first parameter is [%1%], the second is [%2%], etc.<br />
<br />
Parameter substitution happens on all line types, and happens prior to character attribute references or roll variable substitution.<br />
<br />
=== Campaign Attribute ===<br />
You can retrieve properties of the API's Campaign object with the [*C:attributename] syntax. For example, [*C:playerpageid] will retrieve the current player ribbon page from the Campaign object.<br />
<br />
=== Page Attributes ===<br />
If you have set the '''activepage''' parameter, you can retrieve page-related properties with the [*P:attributename] syntax, including the page's UDL parameters.<br />
<br />
=== Repeating Section Values ===<br />
<br />
You can reference repeating attribute data using the syntax [*R:attributename] syntax (similar to referencing standard character attributes). The currently active repeating row information will be used to retrieve attribute values. You can also retrieve the full attribute name for a repeating row attribute by using the [*R>attributename] notation. This is useful to pass to things like chatsetattr.<br />
<br />
See the section named [[#Repeating Section Access (--R)|Repeating Section Access]] for more information.<br />
<br />
=== Array Elements ===<br />
After an array has been declared, the elements can be referenced with [@arrayName(index)]. Array indices start at 0.<br />
<br />
=== ScriptCards Settings ===<br />
It is now possible to reference ScriptCards settings (set with the --# command) using the [~settingname] syntax (ie, [~title] will be replaced with the title setting at the time the reference is interpreted.<br />
<br />
== Deferred Resolution for Meta Scripts ==<br />
{{Meta-ToolboxNav}}As of 1.2.9, ScriptCards supports a deferral character for use when calling another API script with via the <code>--@</code> statement, to defer processing of meta script references so they get processed prior to the sub-API call instead of prior to ScriptCards execution. To defer this processing for meta script ([[Script:SelectManager|SelectManager]], [[Script:Fetch|Fetch]]) by inserting a deferral character into the meta call. For example, if I want to have ScriptCards call [[TokenMod]] as if the token for "Quej Gr'stra" (yes, I let Roll20 name my test NPCs) I could use something like this:<br />
<br />
<pre> --@token-mod|{^& select Quej Gr'stra} _on showname</pre><br />
<br />
The <code>^</code> in between <code>{</code> and <code>&</code> will prevent SelectManager from seeing the call when the ScriptCard script is processed, but the <code>--@</code> statement will remove the deferral character so the command that will be sent by ScriptCards is:<br />
<br />
<pre>!token-mod {& select Quej Gr'stra} --on showname</pre><br />
<br />
With the deferral character removed, SelectManager will see the <code>{& select ...}</code> and do its magic.<br />
<br />
While the default deferral character is <code>^</code>, the deferral character is a setting that can be changed:<br />
<br />
<pre> --#deferralcharacter|%</pre><br />
<br />
Will make <code>%</code> the deferral character for future <code>--@</code> statements in the running script.<br />
<br />
Supported [[API:Meta_Scripts|Meta Script]] structures:<br />
* <code>{^&...}</code> - for [[SelectManager]]<br />
* <code>@^(...)</code> and <code>*^(...)</code> for [[Script:Fetch|Fetch]]<br />
* <code>get^.</code> and <code>set^.</code> for [[Script:Muler|Muler]] (''''' v 1.4.5+ ''''')<br />
<br />
== Arrays ==<br />
<br />
Arrays are a new data type introduced in version 1.1.12 of ScriptCards, and are manipulated with associated function (--~) commands.<br />
<br />
* Arrays are a lists of strings. Items in an array cannot contain the semi-colon (;) character, as that is used to separate parameters in the function code that deals with arrays.<br />
* Arrays are accessed via the --~ script command. In some cases, the value of the tag (variable name) for array commands is not used, and can be a dummy value or simply omitted. I have omitted them in the statements below.<br />
* All commands that DO return a value return string values, even if the content is numeric.<br />
* If a command returns a value and there is some sort of reason that it isn't an array value, you will get "ArrayError" in the return value. This can happen if you reach the end of an array while stepping through it, for example, so checking for "ArrayError" can serve as the end condition for a loop.<br />
* Each array keeps track of its current index, allowing you to step forward and backwards through arrays.<br />
* Any number of arrays can be defined.<br />
* Unlike string variables and roll variables, array variables cannot (currently) be referenced directly. It is necessary to use the function (--~) syntax to manipulate arrays and get values from them as strings for use in other parts of your script.<br />
<br />
== Reentrant Scripts ==<br />
<br />
Reentrant scripts allow you to create buttons in your script code that will re-execute the script at a given label within the code. If you set the reentrant setting (<code>--#reentrant|somevalue</code>) to a non-zero value, your setting and variable information will be preserved between executions. Reentrant script can be used to present menus or choices and then continue acting.<br />
<br />
'''''Important''''': The value of the reentrant setting will be used to identify the appropriate script to resume when reentrancy is used. If more than one character can potentially run the same script at the same time, it is a good practice to include the character ID in the reentrant setting in order to maintain a separate list of variables. Something like:<br />
<br />
<pre><br />
--#reentrant|My Cool Script @{selected|character_id}<br />
</pre><br />
<br />
Reentrant buttons are created with the <code>[rbutton]Caption::ReentryLabel;Parameter[/rbutton]</code> construct. The caption will be displayed on the generated button. <code>ReentryLabel</code> is the name of a label in your script that the button will jump to when clicked, and Parameter will be passed in as a string value called <code>reentryval</code>.<br />
<br />
Example:<br />
<pre><br />
!script {{<br />
--#reentrant|testing<br />
--=Roll|1d20<br />
--+Roll|[$Roll]<br />
--&String|That was a [$Roll.Raw]!<br />
--~x|array;define;MyArray;Apple;Banana;Orange<br />
--+Try it|[rbutton]Hello!::EXEC_PC_SPELL;9[/rbutton]<br />
--X|<br />
<br />
--:EXEC_PC_SPELL|<br />
--+ReentryVal|[&reentryval]<br />
--+The value of Roll is|[$Roll]<br />
--+Value of String|[&String]<br />
--+Array|[@MyArray(0)]<br />
--X|<br />
}}<br />
</pre><br />
<br />
This script sets up some variables and then displays a button labeled "Hello!". If the user clicks the button, the script will be re-entered starting at <code>EXEC_PC_SPELL</code>, which will display the content of the variables from the original execution.<br />
<br />
'''''Note: This section needs to be expanded upon'''''<br />
<br />
==Libraries ==<br />
=== Procedure Libraries ===<br />
<br />
You can now create [[handouts]] in your game in Roll 20 with the name format <code>ScriptCards Library NAME</code>, where <code>NAME</code> is a name you assign to the library. Library names are case sensitive. It is my hope that the more proficient ScriptCards scripters out there will provide procedure libraries (or procedures that can be included in libraries) for others to use to make their scripting life easier. Be they specific to a game system, or to a type of activity, I think a robust set of libraries that GMs could use to enhance their scripting capabilities would be very valuable to the community. Should such things begin to emerge, I’ll create a portion of the ScriptCards Wiki page to house them.<br />
<br />
To include one or more libraries in a script, use the <code>+++libname+++</code> directive (does not need a <code>--</code> line associated with it). Multiple library names can be specified by separating them with semicolons (i.e., <code>+++General;dnd5elib;Colorize+++</code> would include three libraries (General, dnd5elib, and Colorize).<br />
<br />
Included libraries are separated from the main script code by the automatic inclusion of <code>--X|</code> before the first library is appended to the script, and all libraries are loaded at the end of the script before script processing takes place.<br />
<br />
Procedures and labels in libraries can be used just as if they were included in the body of your script. Note that this DOES mean that you could, technically, jump into a library with a direct branch <code>--^</code> or direct branch conditional, but I recommend using libraries to store reusable procedures.<br />
The Notes section of the library handout stores the library code, and is written just like any other ScriptCards code except:<br />
<br />
* They cannot use [[Roll Query|roll queries]] (<code>?{Some Prompt:}</code>) to get information from the user at execution time.<br />
* They cannot use <code>@{}</code> notation to access character and token information.<br />
<br />
Both of these limitation stem from the fact that Procedure Libraries are not processed by the chat server, which is what handles these items.<br />
<br />
Here is an example of handling damage modifications (resistance, vulnerability, and immunity) in {{5E}} with a library:<br />
<br />
<pre><br />
!script {{<br />
+++dnd5elib+++<br />
--#|Damage Modifiers Test<br />
--#targettoken|@{target|token_id}<br />
-->Lib5E_CheckDamageModifiers|ResistType;fire<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] fire damage<br />
<br />
-->Lib5E_CheckDamageModifiers|ResistType;cold<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] cold damage<br />
<br />
-->Lib5E_CheckDamageModifiers|ResistType;poison<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] poison damage<br />
<br />
-->Lib5E_CheckDamageModifiers|ResistType;acid<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] acid damage<br />
<br />
--X|<br />
}}<br />
</pre><br />
<br />
Library content (In a handout called “ScriptCards Library dnd5elib” NOTE: Paste into Notepad first and then paste into the handout in Roll20 to avoid bringing over HTML formatting from the web site):<br />
<br />
<pre><br />
--/|ScriptCards Library: dnd5elib version 0.0.1<br />
--/|Provides various utility procedures for D&D 5E games<br />
<br />
--/|Lib5E_CheckDamageModifiers handle damage resistance, vulnerability, and immunity. <br />
--/|Pass a string variable to be filled with a string to be appended to a dice roll and the damage type <br />
<br />
--:Lib5E_CheckDamageModifiers|damageVariableName;damageType<br />
--&[%1%]|<br />
--?"[*T:npc_vulnerabilities]" -inc "[%2%]"|>_Lib5E_IsVulnerable;[%1%]<br />
--?"[*T:npc_resistances]" -inc "[%2%]"|>_Lib5E_IsResistant;[%1%]<br />
--?"[*T:npc_immunities]" -inc "[%2%]"|>_Lib5E_IsImmune;[%1%]<br />
--<|<br />
<br />
--:_Lib5E_IsVulnerable| --&[%1%]| * 2 [Vulnerable] --<|<br />
--:_Lib5E_IsResistant| --&[%1%]| \ 2 [Resistant] --<|<br />
--:_Lib5E_IsImmune| --&[%1%]| * 0 [Immune] --<|<br />
</pre><br />
<br />
The idea is that the functions in the library create a string that can be appended to a roll to modify the output based on resistances, so you pass <code>Lib5E_CheckDamageModifiers</code> the name of the string variable you want to use and the damage type. The variable ({{c|ResistType}} in this case) will include either nothing, {{c|* 2 [Vulnerable]}}, {{c|\ 2 [Resistant]}}, or {{c|* 0 [Immune]}} which can be included in a roll assignment ({{c|--=}}) to modify the damage as appropriate. The order here might be important if an NPC is misconfigured to be both resistant and immune to the same damage type. Since immune is an absolute, having it last ensures that it will override resistant or vulnerable. A creature that is both vulnerable and resistant (again, misconfigured) will come back as resistant since that condition is checked after vulnerable.<br />
Some notes: I prefix my library labels with either {{c|Lib5E_}} or {{c|_Lib5E_}} as a clarity convention. This isn’t strictly necessary but you should be aware that if two libraries (or if your script and a library) define the same label, the last label defined will win. Since libraries are appended to the end of the script in the order you include them in the {{c|+++libname+++}} directive, you can somewhat control this, but it is probably best to avoid re-declaring labels. <br />
<br />
In my case, items beginning with {{c|Lib5E_}} are intended to be called by scripts, while items beginning with {{c|_Lib5E_}} are intended to be used as subroutines by the “public” procedures. Of course, there is no reason you couldn’t call them directly.<br />
<br />
You might also note that I’ve included some library information in comment lines (<code>--/|</code>) at the top of the library. These are ignored by ScriptCards, and are a good way to convey requirements, parameters, usage information, etc.<br />
<br />
=== Example Libraries ===<br />
<br />
==== dnd5elib ====<br />
<br />
[https://github.com/kjaegers/ScriptCards Download the dnd5elib Library from the ScriptCards GitHub]<br />
<br />
The '''dnd5elib''' library provides a collection of utility procedures that help simplify dealing with the D&D 5E Official Sheet. Some of the procedures in this library require '''chatsetattr''' to be installed in your game. This is a growing library, and currently only has a handful of routines. They are:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Procedure Name !! Notes<br />
|-<br />
| style="white-space:nowrap" | Lib5E_CheckDamageModifiers || This procedure can be used to evaluate vulnerabilities, resistances, and invulnerabilities on an NPC. After setting the --#target| parameters, pass the Lib5E_CheckDamageModifiers procedure a variable name (no reference information) and a damage type (i.e., fire, cold, bludgeoning, etc.), and the procedure will then create a string variable with with a name equal to the first parameter that you passed into the procedure. This variable will contain a string that can be included in a roll line (--=), in order to modify the roll as appropriate. For example, '''-->Lib5E_CheckDamageModifiers|ResistType;fire''' will check the current target character's attributes for "fire" and will either return an empty string (no references), "* 0 [Immune]" if the creature is immune, "\ 2 [Resistant]" if the creature is resistant, or "* 2 [Vulnerable]" if the creature is vulnerable to fire damage.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_DeductSpellSlot || Pass in a character_id and a slot level, and the script will expend one spell slot of that level, capping the value at 0 slots remaining. For Example '''<nowiki>-->Lib5E_DeductSpellSlot|@{selected|character_id};1</nowiki>''' to deduct a first level spell slot from the selected character.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_FindResource || Used to locate a resource value on a character. Pass in a character_id, a resource name, and two variable names. The procedure will check both repeating and non-repeating resources looking for a resource whose name matches what was passed in and return three variables. The first will be a string variable named for the 3rd parameter and contains the attribute name of the resource's "name" field. The second will be a string variable named after parameter 4 and contains the resource's value field attribute name, and the third variable is a Roll Variable, also named after the 4th parameter that contains the current resource value. Example: '''<nowiki>-->Lib5E_FindResource|@{selected|character_id};Crossbow bolts;ResName;ResValue</nowiki>''' will find "Crossbow bolts" as a resource on the character and return [&ResName] which is the name of the resource attribute, [&ResValue] which is the '''name of the attribute that stores the value''' and [$ResValue] which is the current numeric value of the resource.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Global_Attack_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Attack Modifiers (repeating_tohitmod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Bless" for 1d4 active and "Being Cool" for +2 active, I will get a return string " + 1d4 [Bless] + 2 [Being Cool]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Save_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Save Modifiers (repeating_savemod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Bless" for 1d4 active and "Being Cool" for +2 active, I will get a return string " + 1d4 [Bless] + 2 [Being Cool]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Skill_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Skill Modifiers (repeating_skillmod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Guidance" for 1d4 active and "Being Cool" for +2 active, I will get a return string " + 1d4 [Guidance] + 2 [Being Cool]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_AC_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Save Modifiers (repeating_savemod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Shield of Faith" with a value of 2 active, I will get a return string " + 2 [Shield of Faith]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Damage_Modifiers || Pass a character ID and TWO string variable to set the return value. The first string will be for normal damage, and the second will be the additional damage on a crit. This procedure will look through the Global Damage Modifiers (repeating_damagemod_*) for rows that are active (checked on the character sheet) and return two strings with the dice rolls and descriptions for them (for example, if I have "Sneak Attack" with a value of 1d6 normal and 1d6 critical damage active, I will get a return string " + 1d6 [Sneak Attack]" and another string of " + 1d6 [Sneak Attack CRIT]" that can be used in a dice rolls.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_DivineSmiteDice || Used to calculate the number of dice to be rolled for a paladin's Divine Smite. Pass a target token id, a spell slot level, and a string variable to be set to the dice roll amount based on the NPC_TYPE attribute of the target token. The returned variable will contain a dice roll (like "3d8" that can be used in a --= line)<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Character_Summary || Pass a character ID to outputs a mini character sheet, including clickable buttons for attacks, actions, legendary actions, etc. Will automatically detect a PC vs NPC and output the appropriate sections.<br />
|}<br />
<br />
Due to formatting issues with the Wiki, the library code has been moved to a [https://gist.github.com/kjaegers/52f6049ddd257f0a1288aca4bbde13c5 GITHUB GIT]. Please view the GIST in raw mode and copy the text and paste it into a handout called "ScriptCards Library dnd5elib" in your Roll20 Game.<br />
<br />
== What to Know if you are Coming from PowerCards ==<br />
<br />
While ScriptCards and PowerCard have very similar output goals, their internals and use are quite different. The table below summarizes some of the major differences between the scripts. With its built in roll parser and true variable support, ScriptCards allows for much more powerful and flexible macro creation than what is possible in PowerCards simply because of its design.<br />
<br />
::{| class="wikitable"<br />
|-<br />
! PowerCards !! ScriptCards <br />
|-<br />
| With a handful of exceptions, all lines in a PowerCard macro are intended to produce a line of output on the final card. || With ScriptCards, ONLY the <code>--+</code> and <code>--*</code> statement types produces output <br />
|-<br />
| PowerCards lines begin with two dashes (<code>--</code>) followed by a unique tag name for the line, followed by a vertical bar and the content for the line. || ScriptCards lines begin with two dashes (<code>--</code>) followed by a '''statement type identifier''', which is a single character that identifies the type of line to the interpreter. This is followed by a tag (frequently optional), a vertical bar, and the parameters for the statement being executed.<br />
|-<br />
| PowerCard macros are always processed top to bottom. Lines can be hidden so they don't output anything, but there is no looping or branching (<code>--SkipTo</code> looks like a branch, but it just hides all of the lines until the referenced label.) || ScriptCards scripts support true branching, including direct branching (<code>--^</code>) and procedure branching (<code>--></code>) and (<code>--<</code>). Procedures support parameters and a call stack so procedures can be nested to call other procedures. In addition, the --% statement type can be used to create for...next loops.<br />
|-<br />
| All lines in a PowerCards macro need to have unique tags because PowerCards builds the card as a single JavaScript object using the tag names to store what will be displayed. This is why repeated tag names always result in the last one being shown. || ScriptCards tags do not need to be unique, and in the case of many line types are optional.<br />
|-<br />
| PowerCards conditionals result in either showing or hiding the line they are on. || ScriptCards conditionals support branching, variable setting, loop control, and statement block initiation. Because conditional lines do not produce output on their own, the true/false value doesn't impact the display directly.'''''<br />
|-<br />
| PowerCards relies on the Roll20 [[Quantum Roll]] server and [[Inline|inline rolls]] for all dice functions || ScriptCards includes its own dice roll parser, and '''''does not parse''''' [[Inline|inline rolls]]. If an [[Inline|inline roll]] is passed to ScriptCards, it will insert the final value of the roll in the place of the roll in the macro, but they are not part of or parsed by the built-in roll parser and cannot reference ScriptCards variables or updated while the script is running.'''''<br />
|-<br />
| PowerCards RollIDs (often mistaken for variables) are assigned by analyzing the results of an inline roll, and cannot be referenced in other rolls, so you can't roll a <code>1d4</code> and then roll a <code>1d20</code> and add the <code>1d4</code> result because all of the rolls happen on the chat server before PowerCards gets the macro text. || ScriptCards supports two types of variables: <code>Roll Variables</code> and <code>String Variables</code>. Because ScriptCards uses its own roll parser and is not dependent upon the chat server, rolls and their results can be used in other rolls, math functions, output, etc.<br />
|}<br />
<br />
== Example Scripts ==<br />
<br />
'''''Note: The features available in ScriptCards have changed drastically since these examples were written. While these should still work, there are in many cases better ways to do things using language features introduces after these were constructed. Please see the [https://github.com/kjaegers/ScriptCards/tree/main/ScriptExamples Script Examples] section of the official ScriptCards GitHub repository for more updated script examples.<br />
<br />
Below are some sample scripts that utilize the various statement types in ScriptCards:<br />
<br />
=== Divine Smite ===<br />
<br />
This script will prompt the user for a spell slot level to expend on a divine smite. It will check the target's npc_type to see if it is an Undead or Fiend, which adds an additional d8 to the smite roll.<br />
<br />
[[File:ScriptCards Divine Smite.png|Divine Smite Script Output]]<br />
<br />
<pre><br />
!scriptcard {{<br />
--#title|Divine Smite<br />
--=DiceCount|?{Spell Slot Level?|1|2|3|4|5|6|7|8|9} + 1<br />
--=IsFiendOrUndead|0<br />
--?"@{target|npc_type}" -inc fiend|>IsBoosted<br />
--?"@{target|npc_type}" -inc undead|>IsBoosted<br />
--=TotalDice|[$DiceCount] + [$IsFiendOrUndead]<br />
--=SmiteRoll|[$TotalDice]d8<br />
--#emoteText|@{selected|token_name} smites @{target|token_name}<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
--+Smite|deals [$SmiteRoll] radiant damage.<br />
--X|<br />
<br />
--:IsBoosted|<br />
--=IsFiendOrUndead|1<br />
--<|<br />
}}<br />
</pre><br />
<br />
==== How It Works ====<br />
<br />
The first line sets the "title" card parameter to "Divine Smite".<br />
<br />
Line 2 Shows a query to the user asking for the spell slot level, adds one and stores the value in the "DiceCount" Roll Variable. The query/dropdown is generated by the chat server prior to the script being executed.<br />
<br />
Line 3 defaults the "IsFiendOrUndead" Roll Variable to 0.<br />
<br />
Lines 4 and 5 compare the target's "npc_type" attribute (passed by the chat server as text) to see if they include either "undead" or "fiend". If true, the IsBoosted subroutine will be called. No parameters are passed to this subroutine.<br />
<br />
Line 6 sets the "TotalDice" variable to the base (DiceCount) number plus the IsFiendOrUndead number, which will be a 0 or a 1.<br />
<br />
Line 7 calculates "SmiteRoll" by rolling a number of d8 equal to the "TotalDice" value.<br />
<br />
Lines 8-10 set the parameters for the emote, which appears above the card content. By setting the sourceToken and the targetToken, their icons will appear in the emote surrounding the text describing the action.<br />
<br />
Line 11 is the only line that actually produces output on the card. It results in "Smite deals # radiant damage".<br />
<br />
Line 12 ends the script execution, preventing the script from continuing and running the subroutines out of context.<br />
<br />
Lines 14-16 are the IsBoosted subroutine, starting with the :IsBoosted label. The IsFiendOrUndead variable is set to 1, and a return from subroutine is executed.<br />
<br />
=== Alternative Script ===<br />
<br />
<pre>!scriptcard {{<br />
--#title|Divine Smite<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
--=DiceCount|?{Spell Slot Level?|1|2|3|4|5|6|7|8|9} + 1<br />
--?"@{target|npc_type}" -inc fiend -or "@{target|npc_type}" -inc undead|=DiceCount;[$DiceCount.Raw] + 1<br />
--=SmiteRoll|[$DiceCount]d8<br />
--#emoteText|@{selected|token_name} smites @{target|token_name}<br />
--+Smite|deals [$SmiteRoll] radiant damage.<br />
}}</pre><br />
<br />
This version of the Divine Smite script has identical output to the script above, but is greatly simplified by using language features introduced later in the ScriptCards development cycle. Instead of a subroutine that is called based on the undead or fiend values as separate checks, a single conditional is used joined by an -or. The expanded capability of conditionals to set variables is then used to add one to the DiceCount if the conditional statement is true.<br />
<br />
=== Magic Missile ===<br />
<br />
This script demonstrates using a loop and calling a subroutine to fire a number of missiles determine by the spell slot level used to cast the spell.<br />
<br />
[[File:ScriptCards_MagicMissile_Fixed.png|Magic Missile Script Output]]<br />
<br />
<pre><br />
!scriptcard {{ <br />
--#title|Magic Missile<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
--=MissileCount|?{Spell Slot Level?|1|2|3|4|5|6|7|8|9} + 2<br />
--=DisplayCount|1<br />
--=MissileDamage|0<br />
--#leftsub|Slot level ?{Spell Slot Level?}<br />
--#rightsub|Ranged Attack<br />
--#emoteText|Fred uses a level ?{Spell Slot Level?} spell slot to fire [$MissileCount.Total] missiles of magical force!<br />
--:MissileLoop|<br />
-->FireMissile|<br />
--=DisplayCount|[$DisplayCount] + 1<br />
--?[$DisplayCount] -le [$MissileCount]|MissileLoop<br />
--+Total|Total damage is [$MissileDamage]<br />
--X|<br />
<br />
--:FireMissile|<br />
--=ThisMissile|1d4 + 1<br />
--=MissileDamage|[$MissileDamage] + [$ThisMissile]<br />
--+Missile|[$DisplayCount.Total] Hits for [$ThisMissile] [b]force[/b] damage<br />
--<|<br />
}}<br />
</pre><br />
<br />
==== How It Works ====<br />
<br />
Lines 1-3 set the card title, the source token and the target token. Setting these tokens causes their icons/avatars to appear in the Emote section of the card.<br />
<br />
Line 4 asks the user what spell slot level they wish to use to cast magic missile. The number of missiles fired is equal to 2 plus the spell level, and this is stored in the MissileCount variable.<br />
<br />
Line 5 stores a 1 in the DisplayCount variable. This will be used to control the loop to determine the number of missiles fired and the missile number when displaying damage rolls.<br />
<br />
Line 6 initializes MissileDamage to 0<br />
<br />
Line 7 sets the left subtitle to the text "Slot Level #", where # is the spell slot level being used.<br />
<br />
Line 8 sets the right subtitle to the text "Ranged Attack".<br />
<br />
Line 9 sets the emoteText parameter with a description of the action, including the slot level and number of missiles fired.<br />
<br />
Line 10 is a label for the missile firing loop<br />
<br />
Line 11 Calls the "FireMissile" subroutine<br />
<br />
Line 12 increases the DisplayCount variable by 1<br />
<br />
Line 13 Checks to see if there are still missles to fire (DisplayCount <= MissileCount) and if so branches to MissileLoop<br />
<br />
Line 14 Displays the total damage dealt by the spell.<br />
<br />
Line 15 stops execution of the script to prevent out of context execution of the subroutine.<br />
<br />
Lines 76-21 are the FireMissile subroutine, beginning with the FireMissile label. The 1d4+1 is rolled and assigned to "ThisMissile". The result is added to the existing MissileDamage total, and a line for the current missile is displayed with the missile number and the damage for the missile.<br />
<br />
=== Longsword Attack ===<br />
<br />
This script demonstrates a standard 5E D&D melee weapon attack, including detection of misses, fumbles, hits, and critical hits. If installed, alterbars is used to decrement the target's BAR3 value by the damage dealt.<br />
<br />
[[File:ScriptCards Longsword.png|Longsword Script Output]]<br />
<br />
<pre><br />
!scriptcard {{<br />
--#title|Longsword<br />
--#leftsub|Melee Attack<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
--#emoteText|@{selected|token_name} attacks @{target|token_name}<br />
--=TargetAC|@{target|npc_ac}<br />
--?[$TargetAC.Total] -gt 0|DoneWithAC<br />
--=TargetAC|@{target|ac}<br />
--:DoneWithAC|<br />
--=AttackRoll|1d20 + @{selected|strength_mod} [STR] + @{selected|pb} [PROF]<br />
--+Attack|@{selected|token_name} rolls [$AttackRoll] vs AC [$TargetAC].<br />
--?[$AttackRoll.Base] -eq 20|Crit<br />
--?[$AttackRoll.Base] -eq 1|Fumble<br />
--?[$AttackRoll.Total] -ge [$TargetAC.Total]|Hit<br />
--+Miss|The attack missed.<br />
--^Final|<br />
<br />
--:Fumble|<br />
--+Fumble!|The attack went horribly wrong.<br />
--^Final|<br />
<br />
--:Hit|<br />
--=Damage|1d8 + @{selected|strength_mod} [STR]<br />
--+Hit!|The attack hit @{target|token_name} for [$Damage] slashing damage.<br />
--@alter|_target|@{target|token_id} _bar|3 _amount|-[$Damage]<br />
--^Final|<br />
<br />
--:Crit|<br />
--=Damage|1d8 + @{selected|strength_mod} [STR] + 1d8 [CRIT]<br />
--+Critical Hit!|The attack hit @{target|token_name} for [$Damage] slashing damage.<br />
--@alter|_target|@{target|token_id} _bar|3 _amount|-[$Damage]<br />
<br />
--:Final|<br />
}}<br />
</pre><br />
<br />
==== How it Works ====<br />
<br />
In lines 1-5, we set the title, subtitle, and emote text along with the tokens for the emote area.<br />
<br />
Lines 6-9 allow us to determine the AC of the target. On the 5E Roll20 sheet, NPCs armor class is stored in "npc_ac", while PCs armor class is in "ac". First we grab npc_ac and if it is zero, we check AC.<br />
<br />
Line 10 rolls the attack roll, rolling 1d20 and adding the attacker's strength modifier and proficiency bonus<br />
<br />
Line 11 displays the result of the attack roll on the card<br />
<br />
Lines 12-14 determine what kind of result the attack had. If the .Base value of the roll was 20, we branch to "Crit". If it was 1, we branch to "Fumble". If the .Total value of the roll was greater than or equal to the AC that was determined in Lines 6-9, we branch to Hit.<br />
<br />
Assuming we didn't branc anywhere, the result of the attack was a miss, so we display that on line 15 and then branch to "Final"<br />
<br />
This is followed by three branch segments, :Fumble, :Hit, and :Crit. A fumble displays a text message and branches to :Final.<br />
<br />
On a hit or a crit, we roll Damage (adding additional damage dice on a crit). We display a "Hit!" or "Critical Hit!" message and then make an API call to AlterBars, passing it the token id, bar we want to modify (3 in this case), and the amount we want to modify by the Damage value.<br />
<br />
=== Party Health Status ===<br />
<br />
This example calculates the current Hit Points remaining and HP percentage for each character and creates a color-coded display with the current party status.<br />
<br />
[[File:ScriptCards Party Health.png]]<br />
<br />
<pre><br />
!scriptcard {{<br />
--#title|Party Status<br />
--#titleCardBackground|#33CC33<br />
--#oddrowbackground|#bfee90<br />
--#evenrowbackground|#90eebf<br />
-->HealthCheck|@{Quej Grastra|character_id}<br />
-->HealthCheck|@{Brim Cheuto|character_id}<br />
-->HealthCheck|@{Odug Ututees|character_id}<br />
--X|End of card Execution<br />
<br />
--:HealthCheck|<br />
--=HealthPerc|[*[%1%]:hp] / [*[%1%]:hp^] * 100 \ 1<br />
--=HealthColor|000000<br />
--?[$HealthPerc.Total] -gt 50|HealthSkip<br />
--=HealthColor|FF0000<br />
--:HealthSkip|<br />
--+[*[%1%]:character_name]|has [#[$HealthColor.RollText]][*[%1%]:hp] of [*[%1%]:hp^][/#] HP [R]([$HealthPerc.Total]%)[/R]<br />
--<|End of HealthCheck<br />
}}<br />
</pre><br />
<br />
==== How it Works ====<br />
<br />
Lines 1-4, we set the card title, and set the title background and row background colors to shades of green.<br />
<br />
Lines 5-7 make gosub calls the the "HealthCheck" subroutine, passing in the character ID of each of the named characters (these are the names of the characters in my test game)<br />
<br />
Line 8 terminates the script execution.<br />
<br />
The remaining lines of the script are the HealthCheck subroutine, which works like this:<br />
<br />
Line 10 is the subroutine label (:HealthCheck)<br />
<br />
Line 11 uses the character id passed as a parameter and combines it with character attribute lookup *(...) to retrieve the value of "hp" and "hp<nowiki>^</nowiki>" for the character. The <nowiki>^</nowiki> character is used to specify that we want the MAX value for this attribute for the second call. We divide these two numbers and multiple by 100 to get a percentage. Finally, we use integer division by 1 to round the percentage and drop the decimals. The end result gets stored in the HealthPerc roll variable.<br />
<br />
Line 12 defaults to color of the health text to black<br />
<br />
Line 13 check to see if the health percentage is greater than 50. If so, it branches to HealthSkip, preventing the script from executing line 13.<br />
<br />
Line 14 sets the color of the health text to red<br />
<br />
Line 15 is the label that will be branched to from Line 13 to skip the red coloring<br />
<br />
Line 16 again uses character attribute substitution and the passed parameter value to output a display line containing the character name, the colorized health total, and the percentage value. The percentage is right-justified.<br />
<br />
Line 17 returns from the HealthCheck subroutine.<br />
<br />
=== Expanded Magic Missile Script ===<br />
<br />
This is the expanded and enhanced version of the Magic Missile script covered in {{yt|watch?v=u50xvNzS9Zk | this video}}. It includes visual and audio effects, checking and deducting spell slots, and applying damage using either Token-Mod or Alterbars.<br />
<br />
<pre><br />
!scriptcard {{ <br />
--#title|Magic Missile<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
<br />
-->GetAndCheckSlotInformation|<br />
<br />
--=MissileCount|[$SlotLevel] + 2<br />
--=DisplayCount|1<br />
--=MissileDamage|0<br />
--#leftsub|Slot level [$SlotLevel]<br />
--#rightsub|Ranged Attack<br />
--#emoteText|@{selected|character_name} uses a level [$SlotLevel.Total] spell slot to fire [$MissileCount.Total] missiles of magical force!<br />
<br />
--:MissileLoop|<br />
-->FireMissile|<br />
--=DisplayCount|[$DisplayCount] + 1<br />
--?[$DisplayCount] -le [$MissileCount]|MissileLoop<br />
--+Total|Total damage is [$MissileDamage]<br />
-->DeductSpellSlot|<br />
--#rightsub|Level [$SlotLevel] Left: [$SlotsRemaining] <br />
-->PlayEffects|none;burst-smoke;beam-magic;spell_01<br />
-->ApplyDamageTokenmod|@{target|token_id};3;-[$MissileDamage]<br />
-->ApplyDamageAlterbars|@{target|token_id};3;-[$MissileDamage]<br />
--X|<br />
<br />
--:FireMissile|<br />
--=ThisMissile|1d4 + 1<br />
--=MissileDamage|[$MissileDamage] + [$ThisMissile]<br />
--+Missile|[$DisplayCount.Total] Hits for [$ThisMissile] [b]force[/b] damage<br />
--<|<br />
<br />
--:GetAndCheckSlotInformation|<br />
--=SlotLevel|?{Spell Slot Level?|1|2|3|4|5|6|7|8|9}<br />
--=SlotsTotal|[*S:lvl[$SlotLevel]_slots_total]<br />
--=SlotsExpended|[*S:lvl[$SlotLevel]_slots_expended]<br />
--?[$SlotsExpended.Total] -ge [$SlotsTotal.Total]|NoSlotsLeft<br />
--<|<br />
<br />
--:NoSlotsLeft|<br />
--+|[*S:character_name] has no level [$SlotLevel.Total] spell slots available.<br />
--X|<br />
<br />
--:DeductSpellSlot|<br />
--=SlotsExpended|[$SlotsExpended] + 1<br />
--@setattr|_charid [*S:character_id] _lvl[$SlotLevel]_slots_expended|[$SlotsExpended] _silent<br />
--=SlotsRemaining|[$SlotsTotal] - [$SlotsExpended]<br />
--<|<br />
<br />
--:PlayEffects|Parameters are : source effect; target effect; line effect; sound effect<br />
--vtoken|@{selected|token_id} [%1%]<br />
--vtoken|@{target|token_id} [%2%]<br />
--vbetweentokens|@{selected|token_id} @{target|token_id} [%3%]<br />
--@roll20AM|_audio,play,nomenu|[%4%]<br />
--<|<br />
<br />
--:ApplyDamageTokenmod|Parameters are tokenid;bar#;amount<br />
--@token-mod|_ignore-selected _ids [%1%] _set bar[%2%]_value|[%3%]<br />
--<|<br />
<br />
--:ApplyDamageAlterbars|<br />
--@alter|_target|[%1%] _bar|[%2%] _amount|[%3%]<br />
--<|<br />
}}<br />
</pre><br />
<br />
===Hidden Roll===<br />
<br />
A roll where only the GM sees the result of the roll.<br />
[[File:Scriptcards-hiddenroll.png|right]]<br />
<pre><br />
!script {{<br />
--#title|Stealth Check<br />
--=Roll|1d20 + @{selected|stealth}<br />
--+|@{selected|token_name} attempts to move undetected...<br />
--*GMLine|@{selected|token_name} rolled a [$Roll]<br />
}}<br />
</pre><br />
<br />
===Elsewhere===<br />
* {{fpl|10000297/ Scritpcard API Working and Sharing}}<br />
* [https://gist.github.com/dubzilla1/cba439bd1f47ecdd81d0c79a482c4a91 Pathfinder 2E heal macros]<br />
<br />
[[Category:Featured articles]]<br />
[[Category:Macros]]<br />
[[Category:API Commands]]</div>5004103https://wiki.roll20.net/Script:ScriptCardsScript:ScriptCards2022-03-13T15:29:03Z<p>5004103: /* Assign Variable to Built-In Function (--~) */</p>
<hr />
<div>{{revdate}}<br />
{{script overview<br />
|name=ScriptCards<br />
|author=[[Kurt J.]]<br />
|code=ScriptCards<br />
|version=1.6.4<br />
|lastmodified=2022-02-27}}<br />
<br />
== Introduction ==<br />
'''ScriptCards''' provides a feature-rich scripting language built as a Roll20 API script and accessible via the Roll20 chat window and macro system. The normal ScriptCards output is a formatted "card" to the game's {{Text Chat}}. While the visual style of the default output is themed after a D&D 4E Power Card, there is nothing game system specific in ScriptCards. The output is fully customizable, and entirely optional. Scripts can perform game object manipulation and never display anything if desired.<br />
<br />
The ScriptCards language supports variables, looping, conditional statements, branching, functions/subroutines, persistence of data items, object modification, reentrant functionality and much, much more. It includes its own dice roll parser with a number of different rolling options.<br />
<br />
ScriptCards is not game-system specific, and can be used with any system/sheet.<br />
<br />
Current [https://github.com/Roll20/roll20-api-scripts/tree/master/ScriptCards OneClick] Version: '''1.6.4'''<br />
<br />
Current Development Version : '''1.6.5'''<br />
<br />
'''''Note:''''' The documentation below is in the process of being updated for 1.6.2 & later.<br />
<br />
'''''<big>Critically Important: ScriptCards does not parse [[Inline|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.</big>'''''<br />
<br />
=== Links ===<br />
* {{fpl|9752053/ ScriptCards thread on the Roll20 API forum}}<br />
** {{fpl|10000297/ Scritpcard API Working and Sharing thread}}<br />
* [https://github.com/kjaegers/ScriptCards/blob/main/ScriptCards_API/changelog.txt Changelog]<br />
* {{repo|kjaegers/ScriptCards/tree/main/ScriptCards_API ScriptCards_API}} - GitHub repository for source before the one-click version is updated.<br />
* {{repo|kjaegers/ScriptCards/tree/main/ScriptExamples ScriptCards Samples}} - Branch of the GitHub repo that contains sample scripts.<br />
* [https://discord.gg/jSB4wTNpXb Discord Channel]<br />
* {{yt.be|hyR7Jnq4mQM ScriptCards Intro}} 45min, Jan 2021<br />
* {{yt.be|u50xvNzS9Zk ScriptCards Magic Missile Deep Dive}} 39min, Feb 2021<br />
{{#evp:youtube|hyR7Jnq4mQM|[[Script:ScriptCards|ScriptCards]] Introduction|right|770}}<br />
__TOC__<br />
<br />
=== Is ScriptCards Related to [[PowerCards]]? ===<br />
<br />
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.<br />
<br />
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 ({{code|name}}, {{code|leftsub}}, {{code|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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
Check the '''[[#What to Know if you are Coming from PowerCards|What to Know if you are Coming from PowerCards]]'''-section for a comparison table between the two scripts.<br />
<br />
=== What is a ScriptCard Script ===<br />
<br />
A ScriptCard script is text written into the {{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 [[Text Chat|chat window]]. A ScriptCard script is composed of an [[API]] command: <code><nowiki>!scriptcard {{ }}</nowiki></code> 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:<br />
<br />
<pre>!scriptcard {{ }}</pre><br />
<br />
Will produce just a title card that displays “ScriptCards” as the name:<br />
<br />
[[File:Scriptcard blank.png]]<br />
<br />
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 <code><nowiki>{{</nowiki></code> and <code><nowiki>}}</nowiki></code> that direct the API script as to what it should do.<br />
<br />
== Structure of a ScriptCard Line ==<br />
<br />
All ScriptCard lines begin with two dashes, followed by an ''statement identifier character'' that lets ScriptCards what type of line it is. There are many different types of statements, and the bulk if this Wiki entry is dedicated to covering the use and function of each one. <br />
<br />
After the line type identifier, a Tag name 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.<br />
<br />
Following the Tag is a vertical bar, and then the content of the line itself. Again, each type of line might interpret this content differently.<br />
<br />
Example:<br />
<br />
<pre>--#title|Longsword Attack</pre><br />
<br />
In this example:<br />
* '''#''' is the statement identifier character, indicating that this line will be a "settings" statement.<br />
* '''title''' is the Tag name. For the "#" statement type, this indicates what setting we will be updating.<br />
* '''|''' separates the Tag from the Content<br />
* '''Longsword Attack''' is the Content portion of the statement. In this case, it indicates what will be placed in the "title" setting.<br />
<br />
=== Statment Types Quickreference ===<br />
<br />
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.<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Identifier !! Statement Type !! Tag !! Content !! Notes<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--/</nowiki> || Comment || unused || unused || The <code>--/</code> 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--#</nowiki> || 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").<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--+</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--=</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--&</nowiki> || Assign String 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. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--@</nowiki> || 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 (i.e., [[TokenMod|!token-mod]], or [[ChatSetAttr|!setattr]], etc.)<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--:</nowiki> || 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<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--^</nowiki> || Branch To || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--></nowiki> || Call Procedure || 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<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--<</nowiki> || 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.<br />
|- <br />
| style="white-space:nowrap" | <nowiki>--?</nowiki> || Conditional Branch || Condition to be evaluated || True Branch Label<nowiki>|</nowiki>False Branch Label || The condition will be evaluated and execution will jump to one of the two indicated branches (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 included a semicolon separated list of parameters. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--s</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--l</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--v</nowiki> || 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+'''''<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--a</nowiki> || Play Audio Track || Unused || Jukebox track name (case sensitive) || Plays an audio track by name from the Roll20 jukebox. '''''Requires v1.5.2+'''''<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--e</nowiki> || Echo to Chat || Name to send chat command as || Chat message to send || Variable substitution takes place on the tag and content.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--R</nowiki> || Retrieve Repeating Section Row information || "find", "first", or "next" || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--~</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--c</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--i</nowiki> || Information Request || User Prompt;Button Caption || InfoType;VariableName;ParameterText || See full documentation below.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--d</nowiki> || 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. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--%</nowiki> || 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. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--*</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--!</nowiki> || Object Modification || <objectType>:<objectId> || setting:value|setting:value|setting:value... || Set properties of tokens/characters or character attributes ('''''v1.5.0+ required''''')<br />
|}<br />
<br />
== ScriptCard Statement Type Details ==<br />
The sections below detail the individual statement types supported by ScriptCards<br />
<br />
=== Comment (--/) ===<br />
<br />
A --/ statement is ignored by the ScriptCards parser. You can use this type of statement to add comments and informational text to your script. <br />
<br />
Example:<br />
<pre><br />
!script {{<br />
--/|Script Name : Fireball<br />
--/|Purpose : Allow the player to cast a fireball and blow stuff up!<br />
.<br />
.<br />
.<br />
}}<br />
</pre><br />
<br />
=== Set Parameter (--#) ===<br />
<br />
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.<br />
<br />
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.<br />
<br />
'''''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.'''''<br />
<br />
Examples:<br />
<pre><br />
--#title|Magic Missile<br />
--#leftsub|Level 1 Spell<br />
--#rightsub|Force Damage<br />
</pre><br />
<br />
The three examples above set the “title”, “leftsub”, and “rightsub” values for the card to the content value for the line. <br />
<br />
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.<br />
Settings Lines do not produce output lines on the card.<br />
<br />
The following settings are available (note that parameter names are ''not'' case sensitive):<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Name !! Effect/Use !! Default Value !! Type<br />
|-<br />
| 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<br />
|-<br />
| allowplaintextinrolls || If set to a non-zero value, plain character text in rolls will be copied to the roll text || 0 || Per-Line<br />
|-<br />
| bodyFontFace || Name of the font used in the card rows || Helvetica || Global<br />
|-<br />
| bodyFontSize || Size of the text in the card rows || 14px || Global<br />
|-<br />
| bodybackgroundimage || Specify an image (content for a CSS background-image tag) for the body area || none || Global<br />
|-<br />
| buttonBackground || Background color for buttons created with [button][/button] || #1C6EA4 || Per-Line<br />
|-<br />
| buttonBackgroundImage || A CSS specifier for a background image to use for buttons (i.e. url(...);) || empty || Per-Line<br />
|-<br />
| buttonBorderColor || Border (outline) color for buttons created with [button][/button] || #999999 || Per-Line<br />
|-<br />
| buttonFontFace || Font Family specifier for captions on buttons created with [button][/button] || Tahoma || Per-Line<br />
|-<br />
| buttonFontSize|| Text size for captions on buttons created with [button][/button] || x-small || Per-Line<br />
|-<br />
| buttonTextColor|| Text color of labels on buttons created with [button][/button] || #FFFFFF || Per-Line<br />
|-<br />
| 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<br />
|-<br />
| deferralcharacter || Changes the meta script deferral sequence to the specified value || ^ || Per-Line<br />
|-<br />
| diceFontColor|| Color of the dice created with the [d4] [d6], etc. formatting markers || #1C6EA4 || Per-Line<br />
|-<br />
| dicefontsize || Size of the dice created with the [d4] [d6], etc. formatting markers || 3.0em || Per-Line<br />
|-<br />
| 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<br />
|-<br />
| disablerollprocessing || If set to a non-zero value, --= lines will not process dice rolls strings || 0 || Per-Line<br />
|-<br />
| emoteBackground || Background color of the emote area || #f5f5ba || Global<br />
|-<br />
| emoteFont || Name of the font used in emote area (above the title of the output card) || Georgia || Global<br />
|-<br />
| emoteFontColor || Color of the font in the emote area || None (Empty) || Global<br />
|-<br />
| emoteFontSize || Size of the font used in the emote area || 14px || Global<br />
|-<br />
| emoteFontWeight || Font weight for the font in the emote area || bold|| Global<br />
|-<br />
| emoteState || If set to anything other than "visible", the emote portion of the card will not be displayed || visible || Global<br />
|-<br />
| emoteText || Text to display in the emote portion of the card || None (Empty) || Global<br />
|-<br />
| emotefont || Name of the font used in the emote text area || font-family: Georgia, serif; font-weight: bold; || Global<br />
|-<br />
| evenRowBackground || Hex code for the background color for even rows || #eeeeee || Per-Line<br />
|-<br />
| evenRowFontColor || Hex code for the text color for even rows || #000000 || Per-Line<br />
|-<br />
| evenrowbackgroundimage || Specify an image (content for a CSS background-image tag) for the even card rows || none || Per-Line<br />
|-<br />
| executionlimit || Maximum number of script lines the interpreter will try to execute. This prevents "infinite loop" sandbox crashes || 40000 || Global<br />
|-<br />
| hideCard || If set to any non-default value, the entire card output will be suppressed || 0 || Global<br />
|-<br />
| 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<br />
|-<br />
| 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<br />
|-<br />
| lineheight || Vertical size of each line on the output card || normal || Per-Line<br />
|-<br />
| nominmaxhighlight || If set to anything other than "0", rolls will not display crit/fumble/mixed highlight colors. || 0 || Per-Line<br />
|-<br />
| 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<br />
|-<br />
| oddRowBackground || Hex code for the background color for even rows || #d0e4f5 || Per-Line <br />
|-<br />
| oddRowFontColor || Hex code for the text color for odd rows || #000000 || Per-Line<br />
|-<br />
| oddrowbackgroundimage || Specify an image (content for a CSS background-image tag) for the odd crd rows || none || Per-Line<br />
|-<br />
| reentrant || Used to name a script for rentrant button use || 0 || Global<br />
|-<br />
| 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)0 || Global<br />
|-<br />
| rollhilightcolorboth || Background box hilight color if both a 1 and a max on the die are rolled ('''''1.4.4+''''') || #8FA4D4 || Per-Line<br />
|-<br />
| rollhilightcolorcrit || Background box hilight color if the maximum number on the die was rolled ('''''1.4.4+''''') || #88CC88 || Per-Line<br />
|-<br />
| rollhilightcolorfumble || Background box hilight color if a 1 was rolled ('''''1.4.4+''''') || #FFAAAA || Per-Line<br />
|-<br />
| rollhilightcolornormal || Background box hilight color if neither a 1 or a max on the die are rolled ('''''1.4.4+''''') || #FFFEA2 || Per-Line<br />
|- <br />
| rollhilightlineheight || Determines the height of the hilight box placed around roll results ('''''1.4.2+''''') || 1.0em || Per-Line<br />
|-<br />
| roundUp || If set to a non-default value, integer division will round up instead of down || 0 || Per-Line<br />
|-<br />
| showfromfornonwhispers || If set to a non-zero value, will include the sender on cards that aren't whispered || 0 || Global<br />
|-<br />
| 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<br />
|-<br />
| subtitleFontColor || Color of the text in the subtitle areas || #FFFFFF || Global<br />
|-<br />
| subtitleFontFace || Name of the font used on the subtitle sections || Tahoma || Global<br />
|-<br />
| subtitleFontSize || Size of the subtitle font || 13px || Global<br />
|-<br />
| subtitleSeperator || The character(s) that will be placed between leftsub and rightsub || <nowiki>&#x2666</nowiki>; || Global<br />
|-<br />
| tableBorderRadius || CSS specifier for how rounded the borders of the output card are. Use "0px;" for square borders || 6px; || Global<br />
|-<br />
| tableShadow || CSS specifier for the drop shadow under the output card || 5px 3px 3px 0px #aaa; || Global<br />
|-<br />
| tablebgcolor || Background color of the whole card. '''''Normally not visible''''' || #EEEEEE || Global<br />
|-<br />
| tableborder || Color of the border that surrounds the whole card || 2px solid #000000; || Global<br />
|-<br />
| 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<br />
|-<br />
| timezone || IANA Specifier for the local time zone, used in system/date functions || America/New_York || Per-Line<br />
|-<br />
| title || Text displayed in the title area of the card || ScriptCards || Global<br />
|-<br />
| titleCardBackground || A hex color code representing the background color of the title area. || #1c6ea4 || Global<br />
|-<br />
| titleFontColor || Color of the text on the card title || #FFFFFF || Global<br />
|-<br />
| titleFontFace || Name of the font used on the title area || Contrail One || Global<br />
|-<br />
| titleFontLineHeight || Line spacing on the title area || 1.2em || Global<br />
|-<br />
| titleFontSize || Size of the title font || 1.2em || Global<br />
|-<br />
| titlecardbackgroundimage || Specify an image (content for a CSS background-image tag) for the title card area || none || Global<br />
|-<br />
| titlecardbottomborder || Border CSS specifier for the bottom of the title card area || 2px solid #444444; || Global<br />
|-<br />
| titlecardgradient || If set to non-zero value, will place a vertical gradient on the title card area || 0 || Global<br />
|-<br />
| usehollowdice || If set to a non-zero value, the hollow/outline versions of the dice fonts will be used || 0 || Per-Line<br />
|-<br />
| whisper|| Comma separated list of who to whisper the output to. Use "gm" for [[GM|GMs]] and "self" for the sender || none || Global|}<br />
|}<br />
<br />
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). <br />
<br />
''Setting Lines do not produce output lines on the card''<br />
<br />
=== Direct Output (--+) ===<br />
<br />
A direct output line display 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.<br />
<br />
Examples of Direct Output lines:<br />
<pre><br />
--+Hello|World<br />
--+Attack|The monster rolls [$Attack] to hit!<br />
--+Damage|@{target|token_name} is hit for [$Damage] [#3333AA][b]frost[/b][/#] damage.<br />
</pre><br />
<br />
Direct Output lines support inline formatting, roll variable replacement, character attribute references, and procedure variables.<br />
<br />
=== GM Output (--*) ===<br />
<br />
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. <br />
<br />
Example:<br />
<pre><br />
--+PlayerLine|This line is shown on the public card<br />
--*GMLine|This line will only be shown to GMs, on a separate card.<br />
</pre><br />
<br />
=== Roll Variable Assignment (--=) ===<br />
<br />
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.<br />
<br />
'''''All components of a roll equation should be separated with spaces.'''''<br />
<br />
Examples:<br />
<pre><br />
--=MissileDamage|1d4 + 1<br />
--=Attack|1d20 + @{selected|strength_mod} [STR] + @{selected|pb} [PROF]<br />
</pre><br />
<br />
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. Text enclosed in square brackets ([]) is considered "flavor text" and will be added to the result text but does not impact the roll result.<br />
<br />
The following dice formats are supported:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Format Pattern !! Example !! Description<br />
|-<br />
| XdY || 3d8 || Simple format. Roll a Y-sided die X times<br />
|-<br />
| XdYkhZ || 2d20kh1 || Roll Y-sided die X times and keep the highest Z number of dice<br />
|-<br />
| XdYklZ || 4d6kl3 || Roll Y-sided die X times and keep the lowest Z number of dice <br />
|-<br />
| XdY>Z || 5d6>3 || Roll Y-sided die X times and count a 1 for each roll greater than Z <br />
|-<br />
| XdY<Z || 5d6<3 || Roll Y-sided die X times and count a 1 for each roll less than Z <br />
|-<br />
| 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<br />
|-<br />
| 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<br />
|-<br />
| 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)<br />
|-<br />
| 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<br />
|-<br />
| 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).<br />
|-<br />
| 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.<br />
|-<br />
| 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. ('''''v1.5.1''''')<br />
|}<br />
<br />
The following operators are supported in a roll equation:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Operator !! Operation<br />
|-<br />
| + || Addition <br />
|-<br />
| - || Subtraction <br />
|-<br />
| * || Multiplication <br />
|-<br />
| / || Division <br />
|-<br />
| \ || Integer Division (Rounds down) <br />
|-<br />
| % || Modulo (Remainder of Divison)<br />
|}<br />
<br />
Roll Variables can be accessed at any time after they have been created by using the [$VariableName] format, with the following optional modifiers:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Modifier !! Meaning<br />
|-<br />
| No modifier || In a Direct Output Line (<nowiki>--+</nowiki>) 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<br />
|-<br />
| .Total || The end result of the roll equation as an unformatted number <br />
|-<br />
| .Base || The cumulative result of any dice rolled in the Roll Text (Numeric modifiers are not included) <br />
|-<br />
| .Ones || The number of dice in the roll that came up as 1s <br />
|-<br />
| .Aces || The number of dice in the roll that came up as the maximum number on the die <br />
|-<br />
| .Odds || The number of dice in the roll that came up with an odd number <br />
|-<br />
| .Evens || The number of dice in the roll that came up with an even number <br />
|-<br />
| .RollText || The raw text of the roll that was use to generate the results <br />
|-<br />
| .Text || A text representation of the results of the roll, including the numbers rolled for each die <br />
|-<br />
| .tableEntryText || The text portion of the result of a table roll<br />
|-<br />
| .tableEntryImgURL || The image source portion of the result of a table roll<br />
|-<br />
| .tableEntryValue || Numeric value of tableEntryText (via parseInt). If a non-numeric value, will be 0<br />
|-<br />
| .Raw || The total numeric result without any formatting, even if placed somewhere formatting would normally be done. <br />
|}<br />
<br />
Examples:<br />
<pre><br />
--+Total Damage|[$MissileDamage.Total] (roll was 1d4+1)<br />
--+Base Damage|[$MissileDamage.Base] (without the +1)<br />
--=Attack|1d20 + @{selected|strength_mod} [STR] + @{selected|pb} [PROF] + [$BlessBonus] [Bless]<br />
</pre><br />
<br />
In this case, 1d4 will be rolled and stored in “BlessBonus”, which can then be used in the Attack line.<br />
<br />
'''''Mathematical Functions in Roll Expressions '''''<br />
<br />
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:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Expression !! Meaning<br />
|-<br />
| {ABS} || Absolute Value<br />
|-<br />
| {CEIL} || Ceiling value (round up to the next whole number)<br />
|-<br />
| {FLOOR} || Floor value (round down to the next whole number)<br />
|-<br />
| {ROUND} || Round value (round up if the decimal portion is greater than 0.5, otherwise round down) '''Note: As of 1.4.11, ROUND now supports :X as a suffix to round to a given number of decimal places (ie, {ROUND:2}'''<br />
|-<br />
| {NEGATE} || Multiply the value by negative one.<br />
|-<br />
| {SQRT} || Take the square root of the running value.<br />
|-<br />
| {SQUARE} || Square the running value.<br />
|-<br />
| {CUBEROOT} || Take the cube root of the running value.<br />
|-<br />
| {CUBE} || Cube the running value.<br />
|-<br />
| {SIN} || Return the SIN of running value.<br />
|-<br />
| {COS} || Return the COS of running value.<br />
|-<br />
| {TAN} || Return the TAN of running value.<br />
|-<br />
| {ASIN} || Return the ASIN of running value.<br />
|-<br />
| {ACOS} || Return the ACOS of running value.<br />
|-<br />
| {ATAN} || Return the ATAN of running value.<br />
|-<br />
| {MAX:X} || Caps the running value at X. ('''''v1.4.12''''')<br />
|-<br />
| {MIN:X} || If the running value is less than X, set the value to X. ('''''v1.4.12''''')<br />
|-<br />
| {CLAMP:X:Y} || Adjust the running value to remain between X (lower bound) and Y (upper bound) ('''''v1.4.12''''')<br />
|}<br />
<br />
Here are the syntax rules when using the above listed functions:<br />
<br />
Example 1.<br />
<br />
<pre><br />
!script {{<br />
--=output|2.9 {FLOOR}<br />
--+output|[$output]<br />
}}<br />
</pre><br />
<br />
The output from this example is "2".<br />
<br />
Example 2.<br />
<br />
<pre><br />
!script {{<br />
--=output|2.9 {FLOOR} {NEGATE} - 3<br />
--+output|[$output]<br />
}}<br />
</pre><br />
<br />
The output from this example is "-5".<br />
<br />
Basically, a function will use as its input whatever the current "running total" is.<br />
<br />
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.<br />
<br />
<br />
'''''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 <nowiki>[[ ]]</nowiki> 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.<br />
<br />
'''''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.<br />
<br />
'''Rolling on Rollable Tables'''<br />
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.<br />
<br />
''Roll Variable Lines do not produce output lines on the card.''<br />
<br />
=== String Variable Assignment (--&) ===<br />
<br />
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:<br />
<br />
<pre><br />
--&MyText|Hello<br />
</pre><br />
<br />
Here, we assign the text "Hello" to the string variable named MyText. You can also append text to a string variable by prefixing the content with a + sign:<br />
<br />
<pre><br />
--&MyText|+ World<br />
</pre><br />
<br />
If run after the statement above, MyText will now contain "Hello World".<br />
<br />
String variables can be referenced using the syntax [&variablename]<br />
<br />
=== Call API (--@) ===<br />
<br />
ScriptCards can use a Call API instruction to execute other API commands. The Tag contains the API 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 API command is executed.<br />
<br />
Examples:<br />
<pre><br />
--@eh|list<br />
--@alter|_target|@{target|token_id} _bar|3 _amount|-[$Damage]<br />
</pre><br />
<br />
In the first example above, the command <code>!eh list</code> will be executed, calling [[EncounterHelper]]. In the second, {{fpl|1216260/ AlterBars}} is called to modify a token's Bar 3 value.<br />
<br />
'''''Note:''''' When ScriptCards (or any API script) runs other API 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).<br />
<br />
See [[API:Script Index]] for more options.<br />
<br />
=== Branch Label (--:) ===<br />
<br />
A branch label defines a line in your code that can be reached by one of the branching instructions (<nowiki>--^</nowiki>, <nowiki>--></nowiki>, or <nowiki>--?</nowiki>). The Tag serves as the label name, and must be unique on the card.<br />
<br />
The vertical bar (|) separator must be present, but the content portion of the line is unused and can be treated as a comment.<br />
<br />
Examples:<br />
<pre><br />
--:MyLoop|<br />
--:CriticalHit|Will jump here if we roll a critical hit!<br />
</pre><br />
<br />
''A Branch Label line does not produce an output line on the card.''<br />
<br />
=== Branch (--^) === <br />
<br />
A Branch line 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.<br />
<br />
Examples:<br />
<pre><br />
--^MyLoop|Jumps to MyLoop<br />
--^SkipCrit|We didn't crit, so skip the Crit code<br />
</pre><br />
<br />
''A Branch line does not produce an output line on the card.''<br />
<br />
=== Call Procedure (-->) ===<br />
<br />
Similar to a branch, a Call Procedure (sometimes knows 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 (<nowiki>--<</nowiki>) 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 (;).<br />
<br />
Examples:<br />
<pre><br />
-->FixFormat|#3333FF;#999999<br />
</pre><br />
<br />
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%].<br />
<br />
=== Return (--<) ===<br />
<br />
A return instruction marks the end of a Gosub procedure. 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.<br />
<br />
Examples:<br />
<pre><br />
--<|<br />
--<|End of MySub<br />
</pre><br />
<br />
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.<br />
<br />
=== Conditional Statement (--?) ===<br />
<br />
A conditional statement contains some equation in the Tag that will be evaluated. '''''If any part of the comparison can/does contain a space, it needs to be surrounded by double quotes'''''<br />
<br />
Based on the true/false result of the evaluation, one of two execution paths will be taken. These execution paths are detailed in the content section of the statement. The "if true" path is specified first (directly after the vertical bar), and the "if false" path is specified after it, also separated by a vertical bar.<br />
<br />
Example:<br />
<pre><br />
--?[$AttackRoll.Total] -ge [$TargetAC]|Hit|Miss<br />
</pre><br />
<br />
'''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.'''<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Branch Format !! Meaning<br />
|-<br />
| Label || If just a label is specified, execution will branch to that label when the comparison is matched.<br />
|-<br />
| >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 <br />
|-<br />
| =VariableName || The roll variable "VariableName" will be assigned the value following a semicolon (for example, the code "=Roll;1d20" will assign the value "1d20" to a variable named "Roll", if the condition is true).<br />
|-<br />
| &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).<br />
|-<br />
| % or %! || The current for...next loop will perform the "next" action (%) or will break out (%!) <br />
|-<br />
| [ || Code block (see below)<br />
|}<br />
<br />
Examples:<br />
<pre><br />
--?[$AttackRoll.Base] -eq 20|CriticalHit<br />
--?[$AttackRoll.Base] -eq 1|>Fumble;@{selected|dexterity_mod}<br />
--?"@{target|npc_type}" -inc "undead"|&MonsterType;Undead|&MonsterType;Not Undead<br />
--?[$Attack.Total] >= [$ArmorClass]|>Hit|>Miss<br />
</pre><br />
<br />
In the first example, if the Base value of AttackRoll is a 20 (natural 20 on the die) execution will branch to the CriticalHit label.<br />
<br />
In the second example, 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%].<br />
<br />
The third example looks for the word "undead" in the npc_type attribute of the targeted character. If it exists in the text, the MonsterType string variable will be set to "Undead", otherwise it will be set to "Not Undead". <br />
<br />
The final example would call 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.<br />
<br />
''Text that does/may contain a space should be enclosed in double quotes.''<br />
<br />
The following comparison operators are available:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Comparator !! Meaning<br />
|-<br />
| -eq || Equal To <br />
|-<br />
| -eqi || Case insensitive Equal To <br />
|-<br />
| -ne || Not Equal To <br />
|-<br />
| -nei || Case insensitive Not Equal To <br />
|-<br />
| -gt || Greater Than <br />
|-<br />
| -ge || Greater Than or Equal To <br />
|-<br />
| -lt || Less Than <br />
|-<br />
| -le || Less Than or Equal To <br />
|-<br />
| -inc || Includes (text strings). <br />
|-<br />
| -ninc || Does Not Include (text strings). <br />
|}<br />
<br />
Multi-part conditionals are supported with -and and -or as separators. For example:<br />
<br />
<pre><br />
--?[$Attack.Total] -ge @{target|npc_ac} -and [$Attack.Base] -ne 20|HitButNotCrit<br />
</pre><br />
<br />
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):<br />
<br />
true AND false OR true<br />
<br />
Will be evaluated as true. The first two (true and false) will be false, but then false OR true will be true.<br />
<br />
Conversely:<br />
<br />
true or false and false<br />
<br />
Will be false, because the first true and false will evaluate to true, and then true and false will be false.<br />
<br />
'''CODE BLOCKS'''<br />
<br />
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.<br />
<br />
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:<br />
<br />
<pre><br />
!script {{<br />
--=Roll|1d2<br />
--+Roll|[$Roll]<br />
--?[$Roll.Total] -eq 2|[<br />
--&Value|Yep!<br />
--+|We are inside the TRUE portion of the block<br />
--]|[<br />
--&Value|Nope<br />
--+|We are inside the FALSE portion of the block<br />
--]|<br />
--+After|the blocks!<br />
--+Value|[&Value]<br />
}}<br />
</pre><br />
<br />
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 --]|. <br />
<br />
At this time, blocks cannot be nested, and can only be created as part of a conditional (--[ is not a valid statement type)<br />
<br />
''A conditional statement does not produce a line of output on the card.''<br />
<br />
=== Case Statement (--c) ===<br />
<br />
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:<br />
<br />
<pre><br />
!script {{<br />
--#title|Case Statement Testing<br />
--=Roll|1d4<br />
--C[$Roll.Total]|1:>One;[$Roll]|2:>Two;[$Roll]|3:>Three;[$Roll]|4:>Four;[$Roll]<br />
--X|<br />
<br />
--:One| --+Value|was One ([%1%]) --<|<br />
--:Two| --+Value|was Two ([%1%]) --<|<br />
--:Three| --+Value|was Three ([%1%]) --<|<br />
--:Four| --+Value|was Four ([%1%]) --<|<br />
}}<br />
</pre><br />
<br />
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 variable as a parameter.<br />
<br />
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:<br />
<br />
<pre>--c?{Difficulty|10|20|30|40}|10:=BonusHealing;0|20:=BonusHealing;10|30:=BonusHealing;30|40:=BonusHealing;50</pre><br />
<br />
The $BonusHealing variable will then contain either 0, 10, 30, or 50 depending upon the user's choice.<br />
<br />
Using this syntax, the first example in this section could be rewritten as:<br />
<br />
<pre><br />
!script {{<br />
--#title|Case Statement Testing<br />
--=Roll|1d4<br />
--C[$Roll.Total]|1:&Result;One|2:&Result;Two|3:&Result;Three|4:&Result;Four<br />
--+Value|was [&Result] ([$Roll.Raw])<br />
}}<br />
</pre><br />
<br />
Instead of branching, this 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.<br />
<br />
=== Save and Load (--s and --l) ===<br />
<br />
This statement pair is used to either store (--s) or load (--l) data from persistent storage. Items stored in persistent storage remain between card rolls and between Roll20 sessions. There are two types of data that can be stored: settings and roll variables. <br />
<br />
Examples:<br />
<br />
<pre><br />
--Ssettings|GreenStyle<br />
--Srollvariables|FirstCardVars<br />
</pre><br />
<br />
In this case, the tag for the statement determines what type of item is being saved (settings or rollvariables). When saving settings, all non-default settings are written to the named setting storage value. When Roll Variables are saved, all variables that currently exist will be saved to the named storage value.<br />
<br />
Loading stored items simply requires the same command with the --l statement type:<br />
<br />
<pre><br />
--Lsettings|GreenStyle<br />
--Lrollvariables|FirstCardVars<br />
</pre><br />
<br />
When loading settings, all stored settings will be applied to the current card settings. You can override settings by changing them after the load.<br />
<br />
When loading roll variables, the saved variables will be added to (or overwrite if they have the same name) any variables on the current card. This means it is safe to create roll variables before the load statement.<br />
<br />
'''Practical Uses'''<br />
The major intended use of persistent storage is for storing card formats for use in later scripts. For example, the following script:<br />
<br />
<pre><br />
!scriptcard {{<br />
--#titlecardbackground|#22CC22<br />
--#oddrowbackground|#cceecc<br />
--#evenrowbackground|#99ee99<br />
--Ssettings|@{selected|token_name}<br />
}}<br />
</pre><br />
<br />
Would save the titlecardbackground, oddrowbackground, and evenrowbackground settings to a saved list named after the selected token's name. When creating cards for that token to run later, you could include the line:<br />
<br />
<pre><br />
--Lsettings|@{selected|token_name}<br />
</pre><br />
<br />
To load all of the settings at once. By creating these setting sets for each character, you can specify a different color scheme for each character that can then be used in cards with a single formatting line.<br />
<br />
There is a supplemental ! command added to support saved settings:<br />
<br />
<pre><br />
!sc-liststoredsettings<br />
</pre><br />
<br />
Will produce a list of all stored setting names, with buttons to list the setting values stored in each group and a button to delete groups as needed.<br />
<br />
=== Visual Effects (--v) ===<br />
<br />
The --v statement can be used to create visual effects on the tabletop. The tag portion of the statement can be either "token" or "betweentokens". The content portion of the statement contains the required parameters for the effect generation, separated by spaces. If the effect is "none", no effect will be played. If any other value that doesn't match a Roll20 effect name will result in a burst-fire effect.<br />
<br />
For "token" effects, the parameters are the token id for the token the effect happens on, followed by the effect specifier.<br />
<br />
Example:<br />
<pre><br />
--vtoken|@{selected|token_id} burst-fire<br />
</pre><br />
<br />
For "betweentoken" effects, the parameters are the source token id, the target token id, and the effect specifier.<br />
<br />
Example:<br />
<pre><br />
--vbetweentokens|@{selected|token_id} @{target|token_id} beam-magic<br />
</pre><br />
<br />
'''''Version 1.2.8+'''''<br />
<br />
An additional effect specifier, "point" is available in 1.2.8+. This specifier allows you to create a visual effect at a designated X/Y pixel coordinate. Future updates will add custom-vfx support to this option. The parameters are the X and Y coordinates and the effect descriptor. As of version 1.2.9, you can also use custom effect specifiers with Point effects:<br />
<br />
<pre><br />
--vpoint|150 200 burst-fire<br />
</pre><br />
<br />
=== Audio Effects (--a) ===<br />
<br />
'''''Requires version 1.5.2+'''''<br />
<br />
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.<br />
<br />
<pre><br />
--a|SwordHitSound<br />
</pre><br />
<br />
No external APIs are required.<br />
<br />
=== Echo to Chat (--e) ===<br />
<br />
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.<br />
<br />
Example:<br />
<pre><br />
--eThe Ghost|/em hovers around @{selected|character_name}... BOO!<br />
</pre><br />
<br />
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).<br />
<br />
'''''Whispering'''''<br />
<br />
You can use the echo statement to send a whisper, but there's a trick to it. If you execute this code here:<br />
<br />
<pre><br />
--eThe Ghost|/w ExamplePlayerName Boo.<br />
</pre><br />
<br />
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.<br />
<br />
So, in conclusion, it's best to use something like this when you're sending a whisper:<br />
<br />
<pre><br />
!script {{<br />
--#hidecard|1<br />
--&sender|The Ghost<br />
--&receiver|ExamplePlayerName<br />
--&message|Boo.<br />
--e[&sender]|/w [&receiver] [&message]<br />
--eScriptCards|/w gm **Whispered from [&sender] to [&receiver]:** [&message] <br />
}}<br />
</pre><br />
<br />
This will ensure that the message appears in your chat feed as well.<br />
<br />
=== Repeating Section Access (--R) ===<br />
<br />
ScriptCards supports accessing [[Repeating Section]] rows on a character sheet (for example: the attacks, the items, and the repeating resources) with the {{c|--R}} statement type. <br />
<br />
There are three basic commands you can use with --R, and they are specified by <br />
the tag used:<br />
<br />
<br />
'''''The "find" tag'''''<br />
<br />
An Rfind statement is used to search through a repeating field. Here is the general form of such a statement.<br />
<br />
<pre><br />
--Rfind|characterid;EntryName;SectionPrefix;SearchField<br />
</pre><br />
<br />
This is the most direct way to access a repeating section row. Supplying the character ID, followed by what you are looking for (Greatsword, for example), followed by the character sheet's section prefix ({{c|repeating_attack}}), followed by the field to check what you are searching for ({{c|atkname}}) will load the matching section (if found) into the script parsers memory. For example:<br />
<br />
<pre><br />
--Rfind|@{selected|character_id};Greatsword;repeating_attack;atkname<br />
</pre><br />
<br />
Will look at the character's {{c|repeating_attack}} section for an entry with an {{c|atkname}} value equal to "Greatsword". Similarly:<br />
<br />
<pre><br />
--Rfind|@{selected|character_id};Bite;repeating_npcaction;name<br />
</pre><br />
<br />
Will look for a "Bite" action on an NPC's action list.<br />
<br />
<br />
'''''The "first" tag'''''<br />
<br />
<pre><br />
--Rfirst|characterid;section prefix<br />
</pre><br />
<br />
This form of the --R command will look at all of the entries in the specified repeating section and load the first one into memory:<br />
<br />
<pre><br />
--Rfirst|@{selected|character_id};repeating_attack<br />
</pre><br />
<br />
Would load the character's first "repeating_attack" row into memory.<br />
<br />
<br />
'''''The "next" tag'''''<br />
<br />
<pre><br />
--Rnext|<br />
</pre><br />
<br />
No parameters are required for --Rnext, which loads the next entry in the list that was obtained with "first" into memory.<br />
<br />
<br />
'''''Section prefixes and how to use them'''''<br />
<br />
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 open [[D&D 5E by Roll20|this page]], and search for the phrase "repeating sections".<br />
<br />
<br />
'''''Additional information'''''<br />
<br />
However a row is obtained, it will be parsed to replace any attribute references (ie, <code>@{level}</code>) with the corresponding character attribute.<br />
<br />
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".<br />
<br />
You can reference repeating attribute data using the syntax {{c|[*R:attributename]}} syntax (similar to referencing standard character attributes).<br />
<br />
Here are some examples:<br />
<br />
Display the details of the "Greatsword" PC attack:<br />
<br />
<pre><br />
!script {{<br />
--Rfind|@{selected|character_id};Greatsword;repeating_attack;atkname<br />
--+Attack Name|[*R:atkname]<br />
--+Base Damage|[*R:dmgbase]<br />
}}<br />
</pre><br />
<br />
[[File:Scriptcards repeating greatsword.png|Repeating Greatsword Attack]]<br />
<br />
List all of the actions an NPC can take (just actions, not legendary, etc.)<br />
<br />
<pre><br />
!script {{<br />
--#title|NPC Actions<br />
--#leftsub|@{selected|token_name}<br />
--Rfirst|@{selected|character_id};repeating_npcaction<br />
--:DisplayLoop|<br />
--?"[*R:name]" -eq NoRepeatingAttributeLoaded|Done<br />
--+Action:|[*R:name] [*R:attack_damage] [*R:attack_damagetype]<br />
--?"[*R:attack_damage2]" -eq ""|NoSecondaryDamage<br />
--+ |[*R:attack_damage2] [*R:attack_damagetype2]<br />
--:NoSecondaryDamage|<br />
--Rnext|<br />
-->DisplayLoop| <br />
--:Done|<br />
}}<br />
</pre><br />
<br />
[[File:Scriptcards repeating npcactions.png]]<br />
<br />
In the script above, we get the "first" repeating_npcaction and display information about it. We then execute "next" and repeat until we run into "NoRepeatingAttributeLoaded".<br />
<br />
See the section named [[#Repeating Section Values|Repeating Section Values]] for more information.<br />
<br />
<br />
'''''Special debugging command: dump'''''<br />
<pre><br />
--Rdump|<br />
</pre><br />
<br />
The "dump" command will list all of the attributes ScriptCards knows about for the currently loaded repeating row to the [[API Console]] Log.<br />
<br />
=== Assign Variable to Built-In Function (--~) ===<br />
<br />
ScriptCards has the ability to run a function built into the API script and return the results to a variable. Some functions return roll variables, while others return strings. See the function table below for details. The format is:<br />
<br />
<pre>--~VariableName|function;param1;param2;param3;...</Pre><br />
<br />
::{| class="wikitable"<br />
|-<br />
! Function Name !! Parameters !! Description<br />
|-<br />
| distance || token_A_ID;token_B_ID || Calculate the Chebyshev distance in grid units between two tokens. This is the measurement scheme D&D 4E/5E use for diagonal distance measurement<br />
|-<br />
| euclideandistance || token_A_ID;token_B_ID || Calculate the Euclidean distance between two tokens. This is essentially the Pythagorean theorem in action. Returns the result in grid units.<br />
|-<br />
| euclideanpixel || token_A_ID;token_B_ID || Calculate the Euclidean distance between two tokens and returns the result is pixels instead of grid units. <br />
|-<br />
| euclideanlong || token_A_ID;token_B_ID || 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 is calculated instead of before. More accurate over long distances. <br />
|-<br />
| manhattandistance || token_A_ID;token_B_ID || Also called "taxicabdistance" (which is an acceptable function name), this measures to how-many-over, how-many-up/down distance, disallowing diagonal movement.<br />
|-<br />
| getselected || none || 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 the first selected token, VariableName2 the second, etc.<br />
|}<br />
<br />
'''''Functions with Sub Functions'''''<br />
<br />
Most ScriptCards functions are grouped into set as sub functions. The table below lists the major functions and their sub functions.<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Function Name !! Sub Function !! Parameters !! Return Type !! Description<br />
|-<br />
| array || define || arrayname;value1;value2;... || none || Creates an array called "arrayname" and adds value1, value2, etc. to the array<br />
|-<br />
| array || sort || arrayname || none || Sorts the specified array in place in ascending order (alphabetically)<br />
|-<br />
| array || numericsort || arrayname || none || Sorts the specified array in place in ascending order (numerically) ('''''v 1.4.10+ ''''')<br />
|-<br />
| array || add || arrayname;value1;value2;... || none || Adds value1, value2, ... to the existing array "arrayname"<br />
|-<br />
| array || remove || arrayname;value1;value2;... || none || Removes value1, value2, ... from the existing array "arrayname". Resets the array index to 0.<br />
|-<br />
| array || replace || arrayname;currentvalue;newvalue || none || Replaces all occurrences of "currentvalue" in "arrayname" with "newvalue"<br />
|-<br />
| array || setatindex || arrayname;index;newvalue || none || Replaces the array item at index "index" with "newvalue"<br />
|-<br />
| array || getindex || arrayname || stringVariable || Retrieves the current index in "arrayname" and stores it in the supplied string variable<br />
|-<br />
| array || setindex || arrayname;newindex || none || Sets the current index in array "arrayname" to "newindex"<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| array || removeat || arrayname;indexposition || none || Removes the item at index "indexposition" from "arrayname". Resets the current array index to 0.<br />
|-<br />
| array || indexof || arrayname;searchvalue || stringVariable || Searches the array "arrayname" for and item with the value of "searchvalue" and, if found, returns the index of the first matching value or "ArrayError" if not found<br />
|-<br />
| array || getlength || arrayname || stringVariable || Returns the number of items in array "arrayname"<br />
|-<br />
| array || pagetokens || arrayname;tokenid;(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. 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.)<br />
|-<br />
| 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.<br />
|-<br />
| array || stringify || arrayname || stringVariable || Returns all of the items in "arrayname" as a string separated by semicolons (;)<br />
|-<br />
| array || fromstring || arrayname;delimiter;string || unused || Creates an array from "string", splitting "string" on "delimiter" to separate the items<br />
|-<br />
| array || statusmarkers|| arrayname;tokenid || none|| Creates an array (arrayname) of the active statusmarkers (sometimes called Token Markers) for the specified tokenid<br />
|-<br />
| math || angle || math;angle;tokenid;tokenid|| rollVariable || Calculates the angle between two tokens and returns the value in degrees<br />
|-<br />
| math || ceil || math;ceil;value || rollVariable || Rounds '''value''' up to the next integer, dropping any decimal portion of the number<br />
|-<br />
| math || clamp || math;clamp;value;lowerBound;upperBound || rollVariable || Returns '''value''', but restricted to the range of '''lowerBound''' and '''upperBound'''.<br />
|-<br />
| math || floor || math;floor;value || rollVariable || Rounds '''value''' down, dropping any decimal portion of the number<br />
|-<br />
| math || max || math;max;valueA;valueB || rollVariable || Returns the larger of '''valueA''' vs '''valueB'''<br />
|-<br />
| math || min || math;min;valueA;valueB || rollVariable || Returns the smaller of '''valueA''' vs '''valueB'''<br />
|-<br />
| math || round || math;round;value || rollVariable || Rounds '''value''' to the nearest integer<br />
|-<br />
| string || length || string;length;stringValue || rollVariable || Returns the length of '''stringValue''' in characters<br />
|-<br />
| string || before || string;before;searchText;stringValue || stringVariable || Searches '''stringValue''' for '''searchText''' and returns the portion of '''stringValue''' prior to that text<br />
|-<br />
| string || after || string;after;searchText;stringValue || stringVariable || Searches '''stringValue''' for '''searchText''' and returns the portion of '''stringValue''' after that text<br />
|-<br />
| string || left || string;left;count;stringValue || stringVariable || Returns the leftmost '''count''' characters of '''stringValue'''<br />
|-<br />
| string || right || string;right;count;stringValue || stringVariable || Returns the rightmost '''count''' characters of '''stringValue'''<br />
|-<br />
| string || replace || string;replace;searchText;replaceText;stringValue || stringVariable || Replaces '''searchText''' in '''stringValue''' with '''replaceText''' and returns the resulting string<br />
|-<br />
| string || replaceall || string;replace;searchText;replaceText;stringValue || stringVariable || Replaces all intances of '''searchText''' in '''stringValue''' with '''replaceText''' and returns the resulting string '''''Requires 1.2.9+'''''<br />
|-<br />
| string || trim || string;trim;stringValue || stringVariable || Removes leading and trailing spaces from stringValue and returns the result. <br />
|-<br />
| string || substring || string;substring;start;count;stringValue || stringVariable || Returns '''count''' characters starting at '''start''' from '''stringValue'''<br />
|-<br />
| 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.<br />
|-<br />
| string || tolowercase || string;tolowercase;stringValue || stringVariable || Converts the passed string to lower case and assigns to the passed variable name. <br />
|-<br />
| string || touppercase || string || stringVariable || Converts the passed string to upper case and assigns to the passed variable name. <br />
|-<br />
| 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. <br />
|-<br />
| 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.<br />
|-<br />
| 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'''.<br />
|-<br />
| turnorder || clear || none || none || Clears all entries from the {{Turn Tracker}}/Initiative<br />
|-<br />
| turnorder || addtoken || tokenid;trackervalue || none || Adds the token represented by "tokenid" to the initiative tracker with an initiavie value of "trackervalue"<br />
|-<br />
| turnorder || replacetoken || tokenid;trackervalue || none || Replaces the token represented by "tokenid" in the initiative tracker with an initiavie value of "trackervalue". Will add the token if it doesn't exist in the tracker.<br />
|-<br />
| turnorder || removetoken || tokenid || none || Removes the token represented by "tokenid" from the initiative tracker if it exists<br />
|-<br />
| turnorder || addcustom || textlabel;trackervalue || none || Add a custom text entry to the {{Turn Tracker}}/Initiative named "textlabel" with an initiative value of "trackervalue"<br />
|-<br />
| system || date || getdatetime || stringVariable || Returns the date time in the active timezone (see settings) <br />
|-<br />
| system || date || getdate || stringVariable || Returns the date in the active timezone (see settings) <br />
|-<br />
| system || date || gettime || stringVariable || Returns the time in the active timezone (see settings)<br />
|-<br />
| system || dumpvariables || "rolls", "string", or "array" || none || Dumps all of the defined variables of the indicated type to the console log<br />
|-<br />
| system || findability || system;findability;charactername;abilityname || stringVariable || Returns the object ID of the ability on the indicated character or "AbilityNotFound"<br />
|-<br />
|}<br />
<br />
Examples:<br />
<br />
<pre><br />
--~HowFarAway|distance;@{selected|token_id};@{target|token_id}<br />
</pre><br />
<br />
Returns the distance (Chebyshev) between the selected and target tokens and stores it in "HowFarAway".<br />
<br />
<pre><br />
--SelectedDudes|getselected<br />
</pre><br />
<br />
If 5 tokens were selected, 6 variables would be created: SelectedDudesCount (with a value of 5), SelectedDudes1, SelectedDudes2, SelectedDudes3, SelectedDudes4, SelectedDudes5.<br />
<br />
=== Information Request (--i) ===<br />
<br />
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.<br />
<br />
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.<br />
<br />
After the user has clicked the button and responded to the requests, ScriptCards will resume processing the script from where it left off.<br />
<br />
Here is an example “i” line:<br />
<br />
<pre><br />
--IScriptCards needs additional information to continue;Click to select a target and provide information|t;MyNewTarget;Missile1Target||q;MyNameIs;What is your name?<br />
</pre><br />
<br />
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.<br />
<br />
Supported information request types are “t” for target token, and “q” for query.<br />
<br />
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).<br />
<br />
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:<br />
<br />
<pre><br />
q;UserName;What is your name?|Fred|Bob|Sally|Nancy<br />
</pre><br />
<br />
Would have a dropdown menu with four choices.<br />
<br />
=== Object Modification (--!) ===<br />
<br />
'''''Requires ScriptCards version 1.5.0+'''''<br />
<br />
Object modification support is now available in ScriptCards. As of 1.5.0, you can use the --! command to modify object properties in the game. This may help reduce the reliance on the --@ command to run other API commands to modify token/character values. The biggest benefit of this is that the changes happen as the script is processing, so the new values are available right away. <br />
<br />
The format of the command is:<br />
<pre><br />
--!<objectType>:<objectId>|setting:value|setting:value|setting:value...<br />
</pre><br />
<br />
'''objectType''' can be one of "t" for token, "c" for character, or "a" for character attribute<br />
<br />
'''objectId''' can be a token id or a character id (or "S"/"T" for the Source/Target token/char defined with --#sourcetoken and --#targettoken)<br />
<br />
'''setting''' and '''value''' pairs can be chained in a single statement separated by | to impact more than one property/attribute with a single line<br />
<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
Examples:<br />
<br />
Set the value of bar1_value for the selected token to 5:<br />
<pre> --!t:@{selected|token_id}|bar1_value:5</pre><br />
Add 1 to the bar3_value for the selected token:<br />
<br />
<pre> --!t:@{selected|token_id}|bar3_value:+=1</pre><br />
Set bar2_value to 5 and bar2_max to 10 for the selected token<br />
<br />
<pre> --!t:@{selected|token_id}|bar2_value:5|bar2_max:10</pre><br />
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:<br />
<br />
<pre> --!a:@{selected|token_id}|dndstyling:on|size:enormous|!attitude:epic</pre><br />
Adds 50 to the npc_xp attribute for the character represented by the selected token, displaying the value before and after the update:<br />
<br />
<pre><br />
!script {{<br />
--+XP|[*@{selected|token_id}:npc_xp]<br />
--!a:@{selected|token_id}|npc_xp:+=50<br />
--+XP|[*@{selected|token_id}:npc_xp]<br />
}}<br />
</pre><br />
<br />
Note that asynchronous read/update fields (bio, notes, gmnotes) are not currently supported.<br />
<br />
== Inline Formatting ==<br />
<br />
Inline formatting is processed on Direct Output lines only (--+ lines) and the following inline format markup is available:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Formatting Tags !! Description<br />
|-<br />
| [b]..[/b] || Bold the text between the markers <br />
|-<br />
| [i]..[/i] || Italicize the text between the markers <br />
|-<br />
| [u]..[/u] || Underline the text between the markers <br />
|-<br />
| [s]..[/s] || Strike-Thru the text between the markers <br />
|-<br />
| [c]..[/c] || Center alignment <br />
|-<br />
| [l]..[/l] || Left alignment <br />
|-<br />
| [r]..[/r] || Right alignment <br />
|-<br />
| [j]..[/j] || Full justification alignment <br />
|-<br />
| [br] || Line break (translates to <pre><br></pre> in html)<br />
|-<br />
| [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<br />
|-<br />
| [#xxx]..[/#] or [#xxxxxx]..[/#] || Use a 3 or 6 digit hex code to colorize the text between the markers <br />
|-<br />
| [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, <code>[img width=128 height=128]</code> )<br />
|-<br />
| [button]caption::action[/button] || Create a button with the label "caption" that performs the action defined by "action". By default, buttons will be colored according the the buttontextcolor and buttonbackground card settings. You can optionally color individual buttons by specifying a text color and a background color as part of the [button] command (ie, [button:#ffffff:#000000] will create a button with white text on a black background. In order to set a background color, the foreground color must be specified.<br />
|-<br />
| [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. By default, buttons will be colored according the the buttontextcolor and buttonbackground card settings. You can optionally color individual buttons by specifying a text color and a background color as part of the [sheetbutton] command (ie, [sheetbutton:#ffffff:#000000] will create a button with white text on a black background. In order to set a background color, the foreground color must be specified.<br />
|-<br />
| [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. By default, buttons will be colored according the the buttontextcolor and buttonbackground card settings. You can optionally color individual buttons by specifying a text color and a background color as part of the [rbutton] command (ie, [rbutton:#ffffff:#000000] will create a button with white text on a black background. In order to set a background color, the foreground color must be specified.<br />
|-<br />
| [t] || Converted to HTML table tag. Text after the "t" will be included inside the tag (width, border, etc)<br />
|-<br />
| [/t] || Converted to HTML close table tag.<br />
|-<br />
| [tr] || Converted to HTML table row tag. Text after the "tr" will be included inside the tag<br />
|-<br />
| [/tr] || Converted to HTML close table row tag.<br />
|-<br />
| [td] || Converted to HTML table cell tag. Text after the "tr" will be included inside the tag<br />
|-<br />
| [/td] || Converted to HTML close table cell tag.<br />
|}<br />
<br />
Code Example<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Formatting Tags !! Description<br />
|-<br />
| <pre>!script {{<br />
--#title|Inline Formatting Examples<br />
--+|This text [b]is bolded[/b]<br />
--+|This text [i]is italicized[/i]<br />
--+|This text [u]is underlined[/u]<br />
--+Alignment|[l]Left[/l]<br />
--+|[c]Center[/c]<br />
--+|[r]Right[/r]<br />
--+|[j]This long bit of text is justified to fit smoothly into the display area for the card with justified wrapping.[/j]<br />
--+Colorized|[#f00]Red[/#] [#0f0]Green[/#] [#00f]Blue[/#]<br />
--+Button|[button]Do Something::DoOnClick[/button]<br />
--+Button Colors|[button:#000:#f00]Red::RedClick[/button] [button:#000:#0f0]Blue::BlueClick[/button] [button:#000:#00f]Blue::BlueClick[/button]<br />
--+Table:|<br />
--+|[t border=2 width=100%][tr][td]Cell1[/td][td]Cell2[/td][/tr][tr][td]Cell3[/td][td]Cell4[/td][/tr][/t]<br />
}}</pre> || [[File:Sc-formatting_example.png]]<br />
|}<br />
<br />
== Variables ==<br />
<br />
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. While it is possible to assign both a string and a roll variable the same name, doing so will likely result in confusion when looking at the script later, so it is not recommended.<br />
<br />
String Variables are assigned with the --& statement and are referenced using [&variableName] notation.<br />
<br />
Roll Variables are assigned with the --= statement, and the assignment value is always processed by the ScriptCards Roll Processor (resolves dice rolls, etc.)<br />
<br />
There are a handful of variables assigned automatically when a ScriptCard is executed. These are all string variables, and are:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Variable !! Value<br />
|-<br />
| SendingPlayerID || Contains the object ID of the player that sent the macro<br />
|-<br />
| SendingPlayerName || Contains the display name of the player<br />
|-<br />
| SendingPlayerColor || Contains the color code associated with the player<br />
|-<br />
| SendingPlayerSpeakingAs || The contents of the "Speaking As" dropdown window<br />
|-<br />
| SendingPlayerIsGM || Contains 1 if the player is a GM, and 0 if the player is NOT a GM<br />
|}<br />
<br />
== Arrays ==<br />
<br />
Arrays are a special type of variable, and are managed by the function (<nowiki>--~</nowiki> command). All of the array function commands follow the same pattern:<br />
<br />
<pre>--~variableName|array;subcommand;arrayname;param1;param2;param3;...</pre><br />
<br />
Not all array commands return anything to "variableName". The function table above will specify the return type of the command if any.<br />
<br />
There are a couple of different ways to create an array:<br />
<br />
The '''define''' array subcommand creates (or recreates) an array and assigns it values - one for each included parameter after the array name. For example:<br />
<br />
<pre>--~|array;define;Fruits;mango;peach;strawberry;apricot;banana;apple</pre><br />
<br />
will create an array called '''Fruits''' with 6 elements in the order listed in the command (mango, peach, etc.)<br />
<br />
You can also use two other subcommands to create arrays based on tokens:<br />
<br />
<pre>--~Count|array;pagetokens;Everybondy;@{selected|token_id}</pre><br />
<br />
and<br />
<br />
<pre>--~Count|array;selectedtokens;Selected</pre><br />
<br />
In both cases, arrays of tokens will be created, and a string variable called "Count" will be set to the number of tokens in the array. The '''pagetokens''' command returns (by default) all of the tokens on the page that contains the token passed as the parameter after the array name. You can filter the tokens that "pagetokens" includes in the array by appending an optional parameter describing the type of token you are looking for:<br />
<br />
<pre>--~Count|array;pagetokens;Everybondy;@{selected|token_id};npc</pre><br />
<br />
Will return only tokens on the page that represent characters that do not have a ''controlledby'' parameter set. The available options are "all" (default), "char", "graphic", "pc", and "npc".<br />
<br />
The '''selectedtokens''' command returns an array with all of the tokens that were selected when the script was called.<br />
<br />
You can also use an arbitrary string to create an array, specifying a delimiter with the '''fromstring''' command:<br />
<br />
<pre><br />
--&names|Fred<br />
--&names|+,Sally<br />
--&names|+,Ted<br />
--&names|+,Joyce<br />
--~|array;fromstring;,;[&names]<br />
</pre><br />
<br />
The above example builds a comma-separated string and then uses "fromstring" to create an array with 4 elements from it, specifying the comma as the delimiter.<br />
<br />
Finally, you can use the '''statusmarkers''' command to create an array with one entry for each active status marker on a specified token:<br />
<br />
<pre>--~|array;statusmarkers;Conditions;@{selected|token_id}</pre><br />
<br />
will create an array with one entry for each status active on the selected token. The array elements will be the internal name of the status (if you are using custom status marker packs, the names will be specified in the marker pack).<br />
<br />
'''Traversing Arrays'''<br />
<br />
Each array keeps track of an internal index position (starting at 0). Several commands let you manage this index:<br />
<br />
*'''getindex''' returns the current index value<br />
*'''setindex''' sets the index to the specified location in the array<br />
*'''getlength''' returns the number of elements in the array<br />
*'''indexof''' returns the index location of the specified element<br />
<br />
Other commands let you retrieve values from the array:<br />
<br />
*'''getfirst''' sets the index to 0 and returns the value at that position<br />
*'''getnext''' advances the index by 1 and returns the new current value<br />
*'''getprevious''' reduces the index by 1 and returns the new current value<br />
*'''getlast''' sets the index to the last elements in the array and returns the new current value<br />
<br />
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.<br />
<br />
'''Manipulating Array Elements'''<br />
<br />
Several array commands deal with inserting, removing, and modifying elements:<br />
<br />
*'''add''' works just like define, except that it takes an existing array and adds elements to it based on the passed parameters<br />
*'''remove''' looks for items matching each passed parameter and removes them from the indicated array if they exist<br />
*'''removeat''' allows you to specify an index location in the array and remove the element at that position<br />
*'''replace''' searches an array for a value and replaces all occurrences of it with a new value (if found)<br />
*'''sort''' sorts the elements in the array in ascending order<br />
*'''strinfigy''' returns a string variable that includes each array element separated by semicolons (;) <br />
<br />
'''Referencing Array Elements'''<br />
<br />
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.<br />
<br />
<pre><br />
!script {{<br />
--~dummy|array;pagetokens;myarray;@{selected|token_id}<br />
--~count|array;getcount;myarray<br />
--+Total:|There are [&count] graphical objects on the page<br />
--~testvar|array;getfirst;myarray<br />
--:loop|<br />
--+Value|[*[&testvar]:character_name]<br />
--~testvar|array;getnext;myarray<br />
--?[&testvar] -ne ArrayError|loop<br />
--+Loop1|Is Done!<br />
}}<br />
</pre><br />
<br />
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:<br />
<br />
<pre><br />
!script {{<br />
--~dummy|array;pagetokens;myarray;@{selected|token_id}<br />
--~count|array;getcount;myarray<br />
--+Total:|There are [&count] graphical objects on the page<br />
--%loopCounter|1;[&count]<br />
--+Value|[*[@myarray([&loopCounter])]:character_name]<br />
--%|<br />
--+Loop|Is Done!<br />
}}<br />
</pre><br />
<br />
This line : <nowiki>--+Value|[*[@myarray([&loopCounter])]:character_name]</nowiki> uses [@arrayName(index)] format (inside a [*characterid:attribute] syntax) to perform the same task as running through the loop with the index.<br />
<br />
(Note: Additional examples are on the way...)<br />
<br />
== For...Next Loops ==<br />
<br />
For...Next loops in ScriptCards are supported with the with the --% statement type. A loop is defined by starting off with:<br />
<br />
<pre><br />
--%LoopCounter|<start>;<end>;[step]<br />
</pre><br />
<br />
The start and end values are required, while the step parameter is optional. If the step is omitted, it will be assumed to be 1. A string variable named after the line tag ("LoopCounter" in the case above) will be created and will hold the current iteration value for the loop. Here is a real example:<br />
<br />
<pre><br />
--%LoopCounter|1;10;1<br />
</pre><br />
<br />
This will begin a loop identified by "LoopCounter" that will start at 1, increasing by 1 each iteration (the step) until it has completed 10 executions.<br />
<br />
The "next" statement is simply <code>--%|</code>, with no tag or parameters. This indicates to ScriptCards that it should increment the counter and go back to the beginning of the loop. Extending the example above:<br />
<br />
<pre><br />
!script {{<br />
--%LoopCounter|1;10;1<br />
--=Roll|1d20<br />
--+Loop|Counter is [&LoopCounter], roll was [$Roll]<br />
--%|<br />
}}<br />
</pre><br />
<br />
The <code>--%!|</code> sequence will break out of the loop, no matter how many iterations are remaining.<br />
<br />
The % and %! character sequences can also be used as part of a 1.2.1+ non-branching conditional to continue or break the loop:<br />
<br />
<pre><br />
--?"X[&RollInto]X" -eq "XX"|%<br />
</pre><br />
<br />
In this example, if the string variable RollInfo is empty, the loop will return to the top and continue with the next iteration, while:<br />
<br />
<pre><br />
--?"X[&RollInto]X" -eq "XX"|%!<br />
</pre><br />
<br />
Would cause the whole loop to end if the condition were true.<br />
<br />
== Referencing ==<br />
<br />
=== Referencing Overview ===<br />
Referencing allows you to substitute the values of variables, objects, attributes, settings, and the like someplace in a ScriptCards line. The table below gives an overview of the various referencing modes and what each one means. In general, references are enclosed in square brackets ({{c|[}} and {{c|]}}) and begin with a character indicating what kind of reference it is (such as {{c|$}} or {{c|&}}), followed by a descriptor that indicates where the value should come from.<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Character !! Type !! Example !! Notes<br />
|-<br />
| $ || Roll Variable || [$AttackRoll] || Roll variables support a number of modifiers (ie, {{c|[$AttackRoll.Base]}}). See the Roll Variables section below for details<br />
|-<br />
| & || String Variable || [&PlayerName] || <br />
|-<br />
| * || Object Attributes || [*S:character_name] || See Attribute Referencing in the next table for details.<br />
|-<br />
| % || Subroutine Parameters || [%1%] || Only available when a subroutine is called with a {{c|-->}} or similar construct. Parameters are numbered beginning at 1.<br />
|-<br />
| @ || Array Elements || [@Colors(5)] || The name of the array follows the {{c|@}} symbol. The index (zero-based) is in parenthesis after the name.<br />
|-<br />
| ~ || Card Settings || [~title] || Returns the value of the ScriptCards settings (set via {{c|--#}} lines)<br />
|}<br />
<br />
''' Object Attribute Referencing '''<br />
<br />
All object attribute referencing use the {{c|*}} prefix character, with the second (and sometimes third) character providing context).<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Prefix !! Example !! Notes<br />
|-<br />
| *S: || [*S:character_name] || Returns token or character attributes for the token/character specified for the {{c|sourcetoken}} setting. Token attributes are prefixed with {{c|t-}} (ex: {{c|[*S:t-bar3_value]}}).<br />
|-<br />
| *T: || [*T:character_name] || Returns token or character attributes for the token/character specified for the {{c|targettoken}} setting. Token attributes are prefixed with {{c|t-}} (ex: {{c|[*T:t-bar3_value]}}).<br />
|-<br />
| *id: || [*-lkfne34mda4:character_name] || when {{c|*}} is followed by an ID, the token/character will be queried for the attribute value requested.<br />
|-<br />
| *C: || [*C:playerpage] || Returns [[campaign]] attributes.<br />
|-<br />
| *P: || [*P:showgrid] || Returns [[Page Settings|page]] attributes. If an {{c|activepage}} setting has been set, the {{c|activepage}} will be referenced. If not, the current {{c|playerpage}} (where the ribbon is) for the campaign is referenced.<br />
|-<br />
| *R: || [*R:atkname] || Used with {{c|--R}} ([[Repeating Section]]) commands to return the VALUE of the current repeating row item's attribute by name.<br />
|-<br />
| *R> || [*R>atkname] || Used with {{c|--R}} (repeating section) commands to return the full attribute name for a repeating row attribute.<br />
|}<br />
<br />
''' Nested References '''<br />
<br />
Reference syntax can be nested, and will be resolved from inside to outside. For example, given a roll variable {{c|MishapRoll}}, and a series of strings ({{c|Mishap1}}, {{c|Mishap2}}, {{c|Mishap3}}, {{c|Mishap4}}), the following reference will begin by substituting {{c|[$MishapRoll.Raw]}} for the roll's numeric value, and then replace the resulting {{c|MishapX}} string with its value:<br />
<br />
<pre>[&Mishap[$MishapRoll.Raw]]</pre><br />
<br />
=== Roll Variables===<br />
<br />
Roll Variables can be referenced from the content portion of any line type, and from the tag portion of conditional statements. The referenced value is replaced when the line is executed.<br />
<br />
There are several modifiers that can be used to reference parts of a roll:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Modifier !! Meaning<br />
|-<br />
| No modifier || In a Direct Output Line (<nowiki>--+</nowiki>), GM Output Line (<nowiki>--*</nowiki>), or String Assignement (<nowiki>--&</nowiki>), 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<br />
|-<br />
| .Total || The end result of the roll equation. Formatting rules for "No Modifier" apply based on line type. <br />
|-<br />
| .Raw || The total value of the roll variable without any formatting, no matter what kind of line the reference is used in.<br />
|-<br />
| .Base || The cumulative result of any dice rolled in the Roll Text (Numeric modifiers are not included) <br />
|-<br />
| .Ones || The number of dice in the roll that came up as 1s <br />
|-<br />
| .Aces || The number of dice in the roll that came up as the maximum number on the die <br />
|-<br />
| .Odds || The number of dice in the roll that came up with an odd number <br />
|-<br />
| .Evens || The number of dice in the roll that came up with an even number <br />
|-<br />
| .RollText || The raw text of the roll that was use to generate the results <br />
|-<br />
| .Text || A text representation of the results of the roll, including the numbers rolled for each die <br />
|-<br />
| .tableEntryText || The text portion of the result of a table roll<br />
|-<br />
| .tableEntryImgURL || The image source portion of the result of a table roll<br />
|-<br />
| .tableEntryValue || If the tableEntryText is purely numeric, will contain the numeric value<br />
|}<br />
<br />
=== String Variables ===<br />
<br />
To reference a string variable, use the notation {{c|[&variablename]}}. String variables can be referenced in direct output, roll variable assignment, and string variable assignment statements.<br />
<br />
=== Character/Token Attributes ===<br />
<br />
A character or token attribute can be referenced from content portion of any type of line and is substituted when the line is executed. The general format for referencing a character attribute is {{c|[*ID:attribute]}}. ID can be a token ID or a character ID (these start with a dash). Additionally if you have specified a sourceToken or targetToken, you can substitute "S" or "T" for the ID (for example {{c|[*S:npc_type]}} will retrieve the {{c|npc_type}} attribute from the source token.<br />
<br />
By default, all attribute references will be pulled from the '''''character''''' object that the ID represents (either directly or by being a Token ID that represents a character).<br />
<br />
Keep in mind, that if you want to access the "max" of a character attribute (for example, the max hit points), then you cannot trust the name that your roll20 character sheet shows you when you hover your mouse over the max hit points. For example, this reference will not work: {{c|[*S:hp_max]}}. Instead, you need to use this reference: {{c|[*S:hp^]}}.<br />
<br />
If your ID refers to a token, token attributes can be accessed by preceding the attribute name with {{c|t-}}, for example {{c|[*S:t-aura1_radius]}}. Supported token attributes are:<br />
'''(NOTE: As of version 1.6.1 of ScriptCards, the below list is no longer a limitation on the token attributes you can reference. All token attributes available in Roll20 can now be accessed and the need to update the internal list as new attributes are added has been eliminated.)'''<br />
<br />
{|<br />
| t-name || t-id || t-statusmarkers || t-bar1_value<br />
|-<br />
| t-bar1_max || t-bar2_value || t-bar2_max || t-bar3_value<br />
|-<br />
| t-bar3_max || t-top || t-left || t-width<br />
|-<br />
| t-height || t-rotation || t-layer || t-aura1_radius<br />
|-<br />
| t-aura1_color || t-aura2_radius || t-aura2_color || t-aura1_square<br />
|-<br />
| t-aura2_square || t-tint_color || t-light_radius || t-light_dimradius<br />
|-<br />
| t-light_angle || t-light_losangle || t-light_multiplier || t-light_otherplayers<br />
|-<br />
| t-light_hassight || t-flipv || t-fliph || t-controlledby<br />
|-<br />
| t-_cardid || t-_pageid || t-imgsrc || t-bar1_link<br />
|-<br />
| t-bar2_link || t-bar3_link || t-represents || t-layer<br />
|-<br />
| t-isdrawing || t-name || t-gmnotes || t-showname<br />
|-<br />
| t-showplayers_name || t-showplayers_bar1 || t-showplayers_bar2 || t-showplayers_bar3<br />
|-<br />
| t-showplayers_aura1 || t-showplayers_aura2 || t-playersedit_name || t-playersedit_bar1<br />
|-<br />
| t-playersedit_bar2 || t-playersedit_bar3 || t-playersedit_aura1 || t-playersedit_aura2<br />
|-<br />
| t-lastmove || t-adv_fow_view_distance || t-has_bright_light_vision || t-has_night_vision<br />
|-<br />
| t-night_vision_distance || t-emits_bright_light || t-bright_light_distance || t-emits_low_light<br />
|-<br />
| t-low_light_distance || t-has_limit_field_of_vision || t-limit_field_of_vision_center || t-limit_field_of_vision_total<br />
|-<br />
| t-has_limit_field_of_night_vision || t-limit_field_of_night_vision_center || t-limit_field_of_night_vision_total || t-has_directional_bright_light<br />
|-<br />
| t-directional_bright_light_center || t-directional_bright_light_total || t-has_directional_dim_light || t-directional_dim_light_center<br />
|-<br />
| t-directional_dim_light_total || t-lightColor || t-tooltip || |<br />
|}<br />
<br />
'''''It is important to note that some attributes names on tokens have corresponding attribute names on characters, which represent different values. For example, {{c|[*T:id]}} returns the character ID, while {{c|[*T:t-id]}} returns the token ID.'''''<br />
<br />
=== Subroutine Parameters ===<br />
<br />
When using a gosub statement (-->) or a conditional marked as a gosub (prefixing the label with a > character), you can pass any number of parameters separated by semicolons (;) that the code in the subroutine can utilize.<br />
<br />
Subroutine parameters are numbered starting at 1, and are accessed by using the notation [%number%], so the first parameter is [%1%], the second is [%2%], etc.<br />
<br />
Parameter substitution happens on all line types, and happens prior to character attribute references or roll variable substitution.<br />
<br />
=== Campaign Attribute ===<br />
You can retrieve properties of the API's Campaign object with the [*C:attributename] syntax. For example, [*C:playerpageid] will retrieve the current player ribbon page from the Campaign object.<br />
<br />
=== Page Attributes ===<br />
If you have set the '''activepage''' parameter, you can retrieve page-related properties with the [*P:attributename] syntax, including the page's UDL parameters.<br />
<br />
=== Repeating Section Values ===<br />
<br />
You can reference repeating attribute data using the syntax [*R:attributename] syntax (similar to referencing standard character attributes). The currently active repeating row information will be used to retrieve attribute values. You can also retrieve the full attribute name for a repeating row attribute by using the [*R>attributename] notation. This is useful to pass to things like chatsetattr.<br />
<br />
See the section named [[#Repeating Section Access (--R)|Repeating Section Access]] for more information.<br />
<br />
=== Array Elements ===<br />
After an array has been declared, the elements can be referenced with [@arrayName(index)]. Array indices start at 0.<br />
<br />
=== ScriptCards Settings ===<br />
It is now possible to reference ScriptCards settings (set with the --# command) using the [~settingname] syntax (ie, [~title] will be replaced with the title setting at the time the reference is interpreted.<br />
<br />
== Deferred Resolution for Meta Scripts ==<br />
{{Meta-ToolboxNav}}As of 1.2.9, ScriptCards supports a deferral character for use when calling another API script with via the <code>--@</code> statement, to defer processing of meta script references so they get processed prior to the sub-API call instead of prior to ScriptCards execution. To defer this processing for meta script ([[Script:SelectManager|SelectManager]], [[Script:Fetch|Fetch]]) by inserting a deferral character into the meta call. For example, if I want to have ScriptCards call [[TokenMod]] as if the token for "Quej Gr'stra" (yes, I let Roll20 name my test NPCs) I could use something like this:<br />
<br />
<pre> --@token-mod|{^& select Quej Gr'stra} _on showname</pre><br />
<br />
The <code>^</code> in between <code>{</code> and <code>&</code> will prevent SelectManager from seeing the call when the ScriptCard script is processed, but the <code>--@</code> statement will remove the deferral character so the command that will be sent by ScriptCards is:<br />
<br />
<pre>!token-mod {& select Quej Gr'stra} --on showname</pre><br />
<br />
With the deferral character removed, SelectManager will see the <code>{& select ...}</code> and do its magic.<br />
<br />
While the default deferral character is <code>^</code>, the deferral character is a setting that can be changed:<br />
<br />
<pre> --#deferralcharacter|%</pre><br />
<br />
Will make <code>%</code> the deferral character for future <code>--@</code> statements in the running script.<br />
<br />
Supported [[API:Meta_Scripts|Meta Script]] structures:<br />
* <code>{^&...}</code> - for [[SelectManager]]<br />
* <code>@^(...)</code> and <code>*^(...)</code> for [[Script:Fetch|Fetch]]<br />
* <code>get^.</code> and <code>set^.</code> for [[Script:Muler|Muler]] (''''' v 1.4.5+ ''''')<br />
<br />
== Arrays ==<br />
<br />
Arrays are a new data type introduced in version 1.1.12 of ScriptCards, and are manipulated with associated function (--~) commands.<br />
<br />
* Arrays are a lists of strings. Items in an array cannot contain the semi-colon (;) character, as that is used to separate parameters in the function code that deals with arrays.<br />
* Arrays are accessed via the --~ script command. In some cases, the value of the tag (variable name) for array commands is not used, and can be a dummy value or simply omitted. I have omitted them in the statements below.<br />
* All commands that DO return a value return string values, even if the content is numeric.<br />
* If a command returns a value and there is some sort of reason that it isn't an array value, you will get "ArrayError" in the return value. This can happen if you reach the end of an array while stepping through it, for example, so checking for "ArrayError" can serve as the end condition for a loop.<br />
* Each array keeps track of its current index, allowing you to step forward and backwards through arrays.<br />
* Any number of arrays can be defined.<br />
* Unlike string variables and roll variables, array variables cannot (currently) be referenced directly. It is necessary to use the function (--~) syntax to manipulate arrays and get values from them as strings for use in other parts of your script.<br />
<br />
== Reentrant Scripts ==<br />
<br />
Reentrant scripts allow you to create buttons in your script code that will re-execute the script at a given label within the code. If you set the reentrant setting (<code>--#reentrant|somevalue</code>) to a non-zero value, your setting and variable information will be preserved between executions. Reentrant script can be used to present menus or choices and then continue acting.<br />
<br />
'''''Important''''': The value of the reentrant setting will be used to identify the appropriate script to resume when reentrancy is used. If more than one character can potentially run the same script at the same time, it is a good practice to include the character ID in the reentrant setting in order to maintain a separate list of variables. Something like:<br />
<br />
<pre><br />
--#reentrant|My Cool Script @{selected|character_id}<br />
</pre><br />
<br />
Reentrant buttons are created with the <code>[rbutton]Caption::ReentryLabel;Parameter[/rbutton]</code> construct. The caption will be displayed on the generated button. <code>ReentryLabel</code> is the name of a label in your script that the button will jump to when clicked, and Parameter will be passed in as a string value called <code>reentryval</code>.<br />
<br />
Example:<br />
<pre><br />
!script {{<br />
--#reentrant|testing<br />
--=Roll|1d20<br />
--+Roll|[$Roll]<br />
--&String|That was a [$Roll.Raw]!<br />
--~x|array;define;MyArray;Apple;Banana;Orange<br />
--+Try it|[rbutton]Hello!::EXEC_PC_SPELL;9[/rbutton]<br />
--X|<br />
<br />
--:EXEC_PC_SPELL|<br />
--+ReentryVal|[&reentryval]<br />
--+The value of Roll is|[$Roll]<br />
--+Value of String|[&String]<br />
--+Array|[@MyArray(0)]<br />
--X|<br />
}}<br />
</pre><br />
<br />
This script sets up some variables and then displays a button labeled "Hello!". If the user clicks the button, the script will be re-entered starting at <code>EXEC_PC_SPELL</code>, which will display the content of the variables from the original execution.<br />
<br />
'''''Note: This section needs to be expanded upon'''''<br />
<br />
==Libraries ==<br />
=== Procedure Libraries ===<br />
<br />
You can now create [[handouts]] in your game in Roll 20 with the name format <code>ScriptCards Library NAME</code>, where <code>NAME</code> is a name you assign to the library. Library names are case sensitive. It is my hope that the more proficient ScriptCards scripters out there will provide procedure libraries (or procedures that can be included in libraries) for others to use to make their scripting life easier. Be they specific to a game system, or to a type of activity, I think a robust set of libraries that GMs could use to enhance their scripting capabilities would be very valuable to the community. Should such things begin to emerge, I’ll create a portion of the ScriptCards Wiki page to house them.<br />
<br />
To include one or more libraries in a script, use the <code>+++libname+++</code> directive (does not need a <code>--</code> line associated with it). Multiple library names can be specified by separating them with semicolons (i.e., <code>+++General;dnd5elib;Colorize+++</code> would include three libraries (General, dnd5elib, and Colorize).<br />
<br />
Included libraries are separated from the main script code by the automatic inclusion of <code>--X|</code> before the first library is appended to the script, and all libraries are loaded at the end of the script before script processing takes place.<br />
<br />
Procedures and labels in libraries can be used just as if they were included in the body of your script. Note that this DOES mean that you could, technically, jump into a library with a direct branch <code>--^</code> or direct branch conditional, but I recommend using libraries to store reusable procedures.<br />
The Notes section of the library handout stores the library code, and is written just like any other ScriptCards code except:<br />
<br />
* They cannot use [[Roll Query|roll queries]] (<code>?{Some Prompt:}</code>) to get information from the user at execution time.<br />
* They cannot use <code>@{}</code> notation to access character and token information.<br />
<br />
Both of these limitation stem from the fact that Procedure Libraries are not processed by the chat server, which is what handles these items.<br />
<br />
Here is an example of handling damage modifications (resistance, vulnerability, and immunity) in {{5E}} with a library:<br />
<br />
<pre><br />
!script {{<br />
+++dnd5elib+++<br />
--#|Damage Modifiers Test<br />
--#targettoken|@{target|token_id}<br />
-->Lib5E_CheckDamageModifiers|ResistType;fire<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] fire damage<br />
<br />
-->Lib5E_CheckDamageModifiers|ResistType;cold<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] cold damage<br />
<br />
-->Lib5E_CheckDamageModifiers|ResistType;poison<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] poison damage<br />
<br />
-->Lib5E_CheckDamageModifiers|ResistType;acid<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] acid damage<br />
<br />
--X|<br />
}}<br />
</pre><br />
<br />
Library content (In a handout called “ScriptCards Library dnd5elib” NOTE: Paste into Notepad first and then paste into the handout in Roll20 to avoid bringing over HTML formatting from the web site):<br />
<br />
<pre><br />
--/|ScriptCards Library: dnd5elib version 0.0.1<br />
--/|Provides various utility procedures for D&D 5E games<br />
<br />
--/|Lib5E_CheckDamageModifiers handle damage resistance, vulnerability, and immunity. <br />
--/|Pass a string variable to be filled with a string to be appended to a dice roll and the damage type <br />
<br />
--:Lib5E_CheckDamageModifiers|damageVariableName;damageType<br />
--&[%1%]|<br />
--?"[*T:npc_vulnerabilities]" -inc "[%2%]"|>_Lib5E_IsVulnerable;[%1%]<br />
--?"[*T:npc_resistances]" -inc "[%2%]"|>_Lib5E_IsResistant;[%1%]<br />
--?"[*T:npc_immunities]" -inc "[%2%]"|>_Lib5E_IsImmune;[%1%]<br />
--<|<br />
<br />
--:_Lib5E_IsVulnerable| --&[%1%]| * 2 [Vulnerable] --<|<br />
--:_Lib5E_IsResistant| --&[%1%]| \ 2 [Resistant] --<|<br />
--:_Lib5E_IsImmune| --&[%1%]| * 0 [Immune] --<|<br />
</pre><br />
<br />
The idea is that the functions in the library create a string that can be appended to a roll to modify the output based on resistances, so you pass <code>Lib5E_CheckDamageModifiers</code> the name of the string variable you want to use and the damage type. The variable ({{c|ResistType}} in this case) will include either nothing, {{c|* 2 [Vulnerable]}}, {{c|\ 2 [Resistant]}}, or {{c|* 0 [Immune]}} which can be included in a roll assignment ({{c|--=}}) to modify the damage as appropriate. The order here might be important if an NPC is misconfigured to be both resistant and immune to the same damage type. Since immune is an absolute, having it last ensures that it will override resistant or vulnerable. A creature that is both vulnerable and resistant (again, misconfigured) will come back as resistant since that condition is checked after vulnerable.<br />
Some notes: I prefix my library labels with either {{c|Lib5E_}} or {{c|_Lib5E_}} as a clarity convention. This isn’t strictly necessary but you should be aware that if two libraries (or if your script and a library) define the same label, the last label defined will win. Since libraries are appended to the end of the script in the order you include them in the {{c|+++libname+++}} directive, you can somewhat control this, but it is probably best to avoid re-declaring labels. <br />
<br />
In my case, items beginning with {{c|Lib5E_}} are intended to be called by scripts, while items beginning with {{c|_Lib5E_}} are intended to be used as subroutines by the “public” procedures. Of course, there is no reason you couldn’t call them directly.<br />
<br />
You might also note that I’ve included some library information in comment lines (<code>--/|</code>) at the top of the library. These are ignored by ScriptCards, and are a good way to convey requirements, parameters, usage information, etc.<br />
<br />
=== Example Libraries ===<br />
<br />
==== dnd5elib ====<br />
<br />
[https://github.com/kjaegers/ScriptCards Download the dnd5elib Library from the ScriptCards GitHub]<br />
<br />
The '''dnd5elib''' library provides a collection of utility procedures that help simplify dealing with the D&D 5E Official Sheet. Some of the procedures in this library require '''chatsetattr''' to be installed in your game. This is a growing library, and currently only has a handful of routines. They are:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Procedure Name !! Notes<br />
|-<br />
| style="white-space:nowrap" | Lib5E_CheckDamageModifiers || This procedure can be used to evaluate vulnerabilities, resistances, and invulnerabilities on an NPC. After setting the --#target| parameters, pass the Lib5E_CheckDamageModifiers procedure a variable name (no reference information) and a damage type (i.e., fire, cold, bludgeoning, etc.), and the procedure will then create a string variable with with a name equal to the first parameter that you passed into the procedure. This variable will contain a string that can be included in a roll line (--=), in order to modify the roll as appropriate. For example, '''-->Lib5E_CheckDamageModifiers|ResistType;fire''' will check the current target character's attributes for "fire" and will either return an empty string (no references), "* 0 [Immune]" if the creature is immune, "\ 2 [Resistant]" if the creature is resistant, or "* 2 [Vulnerable]" if the creature is vulnerable to fire damage.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_DeductSpellSlot || Pass in a character_id and a slot level, and the script will expend one spell slot of that level, capping the value at 0 slots remaining. For Example '''<nowiki>-->Lib5E_DeductSpellSlot|@{selected|character_id};1</nowiki>''' to deduct a first level spell slot from the selected character.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_FindResource || Used to locate a resource value on a character. Pass in a character_id, a resource name, and two variable names. The procedure will check both repeating and non-repeating resources looking for a resource whose name matches what was passed in and return three variables. The first will be a string variable named for the 3rd parameter and contains the attribute name of the resource's "name" field. The second will be a string variable named after parameter 4 and contains the resource's value field attribute name, and the third variable is a Roll Variable, also named after the 4th parameter that contains the current resource value. Example: '''<nowiki>-->Lib5E_FindResource|@{selected|character_id};Crossbow bolts;ResName;ResValue</nowiki>''' will find "Crossbow bolts" as a resource on the character and return [&ResName] which is the name of the resource attribute, [&ResValue] which is the '''name of the attribute that stores the value''' and [$ResValue] which is the current numeric value of the resource.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Global_Attack_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Attack Modifiers (repeating_tohitmod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Bless" for 1d4 active and "Being Cool" for +2 active, I will get a return string " + 1d4 [Bless] + 2 [Being Cool]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Save_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Save Modifiers (repeating_savemod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Bless" for 1d4 active and "Being Cool" for +2 active, I will get a return string " + 1d4 [Bless] + 2 [Being Cool]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Skill_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Skill Modifiers (repeating_skillmod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Guidance" for 1d4 active and "Being Cool" for +2 active, I will get a return string " + 1d4 [Guidance] + 2 [Being Cool]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_AC_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Save Modifiers (repeating_savemod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Shield of Faith" with a value of 2 active, I will get a return string " + 2 [Shield of Faith]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Damage_Modifiers || Pass a character ID and TWO string variable to set the return value. The first string will be for normal damage, and the second will be the additional damage on a crit. This procedure will look through the Global Damage Modifiers (repeating_damagemod_*) for rows that are active (checked on the character sheet) and return two strings with the dice rolls and descriptions for them (for example, if I have "Sneak Attack" with a value of 1d6 normal and 1d6 critical damage active, I will get a return string " + 1d6 [Sneak Attack]" and another string of " + 1d6 [Sneak Attack CRIT]" that can be used in a dice rolls.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_DivineSmiteDice || Used to calculate the number of dice to be rolled for a paladin's Divine Smite. Pass a target token id, a spell slot level, and a string variable to be set to the dice roll amount based on the NPC_TYPE attribute of the target token. The returned variable will contain a dice roll (like "3d8" that can be used in a --= line)<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Character_Summary || Pass a character ID to outputs a mini character sheet, including clickable buttons for attacks, actions, legendary actions, etc. Will automatically detect a PC vs NPC and output the appropriate sections.<br />
|}<br />
<br />
Due to formatting issues with the Wiki, the library code has been moved to a [https://gist.github.com/kjaegers/52f6049ddd257f0a1288aca4bbde13c5 GITHUB GIT]. Please view the GIST in raw mode and copy the text and paste it into a handout called "ScriptCards Library dnd5elib" in your Roll20 Game.<br />
<br />
== What to Know if you are Coming from PowerCards ==<br />
<br />
While ScriptCards and PowerCard have very similar output goals, their internals and use are quite different. The table below summarizes some of the major differences between the scripts. With its built in roll parser and true variable support, ScriptCards allows for much more powerful and flexible macro creation than what is possible in PowerCards simply because of its design.<br />
<br />
::{| class="wikitable"<br />
|-<br />
! PowerCards !! ScriptCards <br />
|-<br />
| With a handful of exceptions, all lines in a PowerCard macro are intended to produce a line of output on the final card. || With ScriptCards, ONLY the <code>--+</code> and <code>--*</code> statement types produces output <br />
|-<br />
| PowerCards lines begin with two dashes (<code>--</code>) followed by a unique tag name for the line, followed by a vertical bar and the content for the line. || ScriptCards lines begin with two dashes (<code>--</code>) followed by a '''statement type identifier''', which is a single character that identifies the type of line to the interpreter. This is followed by a tag (frequently optional), a vertical bar, and the parameters for the statement being executed.<br />
|-<br />
| PowerCard macros are always processed top to bottom. Lines can be hidden so they don't output anything, but there is no looping or branching (<code>--SkipTo</code> looks like a branch, but it just hides all of the lines until the referenced label.) || ScriptCards scripts support true branching, including direct branching (<code>--^</code>) and procedure branching (<code>--></code>) and (<code>--<</code>). Procedures support parameters and a call stack so procedures can be nested to call other procedures. In addition, the --% statement type can be used to create for...next loops.<br />
|-<br />
| All lines in a PowerCards macro need to have unique tags because PowerCards builds the card as a single JavaScript object using the tag names to store what will be displayed. This is why repeated tag names always result in the last one being shown. || ScriptCards tags do not need to be unique, and in the case of many line types are optional.<br />
|-<br />
| PowerCards conditionals result in either showing or hiding the line they are on. || ScriptCards conditionals support branching, variable setting, loop control, and statement block initiation. Because conditional lines do not produce output on their own, the true/false value doesn't impact the display directly.'''''<br />
|-<br />
| PowerCards relies on the Roll20 [[Quantum Roll]] server and [[Inline|inline rolls]] for all dice functions || ScriptCards includes its own dice roll parser, and '''''does not parse''''' [[Inline|inline rolls]]. If an [[Inline|inline roll]] is passed to ScriptCards, it will insert the final value of the roll in the place of the roll in the macro, but they are not part of or parsed by the built-in roll parser and cannot reference ScriptCards variables or updated while the script is running.'''''<br />
|-<br />
| PowerCards RollIDs (often mistaken for variables) are assigned by analyzing the results of an inline roll, and cannot be referenced in other rolls, so you can't roll a <code>1d4</code> and then roll a <code>1d20</code> and add the <code>1d4</code> result because all of the rolls happen on the chat server before PowerCards gets the macro text. || ScriptCards supports two types of variables: <code>Roll Variables</code> and <code>String Variables</code>. Because ScriptCards uses its own roll parser and is not dependent upon the chat server, rolls and their results can be used in other rolls, math functions, output, etc.<br />
|}<br />
<br />
== Example Scripts ==<br />
<br />
'''''Note: The features available in ScriptCards have changed drastically since these examples were written. While these should still work, there are in many cases better ways to do things using language features introduces after these were constructed. Please see the [https://github.com/kjaegers/ScriptCards/tree/main/ScriptExamples Script Examples] section of the official ScriptCards GitHub repository for more updated script examples.<br />
<br />
Below are some sample scripts that utilize the various statement types in ScriptCards:<br />
<br />
=== Divine Smite ===<br />
<br />
This script will prompt the user for a spell slot level to expend on a divine smite. It will check the target's npc_type to see if it is an Undead or Fiend, which adds an additional d8 to the smite roll.<br />
<br />
[[File:ScriptCards Divine Smite.png|Divine Smite Script Output]]<br />
<br />
<pre><br />
!scriptcard {{<br />
--#title|Divine Smite<br />
--=DiceCount|?{Spell Slot Level?|1|2|3|4|5|6|7|8|9} + 1<br />
--=IsFiendOrUndead|0<br />
--?"@{target|npc_type}" -inc fiend|>IsBoosted<br />
--?"@{target|npc_type}" -inc undead|>IsBoosted<br />
--=TotalDice|[$DiceCount] + [$IsFiendOrUndead]<br />
--=SmiteRoll|[$TotalDice]d8<br />
--#emoteText|@{selected|token_name} smites @{target|token_name}<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
--+Smite|deals [$SmiteRoll] radiant damage.<br />
--X|<br />
<br />
--:IsBoosted|<br />
--=IsFiendOrUndead|1<br />
--<|<br />
}}<br />
</pre><br />
<br />
==== How It Works ====<br />
<br />
The first line sets the "title" card parameter to "Divine Smite".<br />
<br />
Line 2 Shows a query to the user asking for the spell slot level, adds one and stores the value in the "DiceCount" Roll Variable. The query/dropdown is generated by the chat server prior to the script being executed.<br />
<br />
Line 3 defaults the "IsFiendOrUndead" Roll Variable to 0.<br />
<br />
Lines 4 and 5 compare the target's "npc_type" attribute (passed by the chat server as text) to see if they include either "undead" or "fiend". If true, the IsBoosted subroutine will be called. No parameters are passed to this subroutine.<br />
<br />
Line 6 sets the "TotalDice" variable to the base (DiceCount) number plus the IsFiendOrUndead number, which will be a 0 or a 1.<br />
<br />
Line 7 calculates "SmiteRoll" by rolling a number of d8 equal to the "TotalDice" value.<br />
<br />
Lines 8-10 set the parameters for the emote, which appears above the card content. By setting the sourceToken and the targetToken, their icons will appear in the emote surrounding the text describing the action.<br />
<br />
Line 11 is the only line that actually produces output on the card. It results in "Smite deals # radiant damage".<br />
<br />
Line 12 ends the script execution, preventing the script from continuing and running the subroutines out of context.<br />
<br />
Lines 14-16 are the IsBoosted subroutine, starting with the :IsBoosted label. The IsFiendOrUndead variable is set to 1, and a return from subroutine is executed.<br />
<br />
=== Alternative Script ===<br />
<br />
<pre>!scriptcard {{<br />
--#title|Divine Smite<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
--=DiceCount|?{Spell Slot Level?|1|2|3|4|5|6|7|8|9} + 1<br />
--?"@{target|npc_type}" -inc fiend -or "@{target|npc_type}" -inc undead|=DiceCount;[$DiceCount.Raw] + 1<br />
--=SmiteRoll|[$DiceCount]d8<br />
--#emoteText|@{selected|token_name} smites @{target|token_name}<br />
--+Smite|deals [$SmiteRoll] radiant damage.<br />
}}</pre><br />
<br />
This version of the Divine Smite script has identical output to the script above, but is greatly simplified by using language features introduced later in the ScriptCards development cycle. Instead of a subroutine that is called based on the undead or fiend values as separate checks, a single conditional is used joined by an -or. The expanded capability of conditionals to set variables is then used to add one to the DiceCount if the conditional statement is true.<br />
<br />
=== Magic Missile ===<br />
<br />
This script demonstrates using a loop and calling a subroutine to fire a number of missiles determine by the spell slot level used to cast the spell.<br />
<br />
[[File:ScriptCards_MagicMissile_Fixed.png|Magic Missile Script Output]]<br />
<br />
<pre><br />
!scriptcard {{ <br />
--#title|Magic Missile<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
--=MissileCount|?{Spell Slot Level?|1|2|3|4|5|6|7|8|9} + 2<br />
--=DisplayCount|1<br />
--=MissileDamage|0<br />
--#leftsub|Slot level ?{Spell Slot Level?}<br />
--#rightsub|Ranged Attack<br />
--#emoteText|Fred uses a level ?{Spell Slot Level?} spell slot to fire [$MissileCount.Total] missiles of magical force!<br />
--:MissileLoop|<br />
-->FireMissile|<br />
--=DisplayCount|[$DisplayCount] + 1<br />
--?[$DisplayCount] -le [$MissileCount]|MissileLoop<br />
--+Total|Total damage is [$MissileDamage]<br />
--X|<br />
<br />
--:FireMissile|<br />
--=ThisMissile|1d4 + 1<br />
--=MissileDamage|[$MissileDamage] + [$ThisMissile]<br />
--+Missile|[$DisplayCount.Total] Hits for [$ThisMissile] [b]force[/b] damage<br />
--<|<br />
}}<br />
</pre><br />
<br />
==== How It Works ====<br />
<br />
Lines 1-3 set the card title, the source token and the target token. Setting these tokens causes their icons/avatars to appear in the Emote section of the card.<br />
<br />
Line 4 asks the user what spell slot level they wish to use to cast magic missile. The number of missiles fired is equal to 2 plus the spell level, and this is stored in the MissileCount variable.<br />
<br />
Line 5 stores a 1 in the DisplayCount variable. This will be used to control the loop to determine the number of missiles fired and the missile number when displaying damage rolls.<br />
<br />
Line 6 initializes MissileDamage to 0<br />
<br />
Line 7 sets the left subtitle to the text "Slot Level #", where # is the spell slot level being used.<br />
<br />
Line 8 sets the right subtitle to the text "Ranged Attack".<br />
<br />
Line 9 sets the emoteText parameter with a description of the action, including the slot level and number of missiles fired.<br />
<br />
Line 10 is a label for the missile firing loop<br />
<br />
Line 11 Calls the "FireMissile" subroutine<br />
<br />
Line 12 increases the DisplayCount variable by 1<br />
<br />
Line 13 Checks to see if there are still missles to fire (DisplayCount <= MissileCount) and if so branches to MissileLoop<br />
<br />
Line 14 Displays the total damage dealt by the spell.<br />
<br />
Line 15 stops execution of the script to prevent out of context execution of the subroutine.<br />
<br />
Lines 76-21 are the FireMissile subroutine, beginning with the FireMissile label. The 1d4+1 is rolled and assigned to "ThisMissile". The result is added to the existing MissileDamage total, and a line for the current missile is displayed with the missile number and the damage for the missile.<br />
<br />
=== Longsword Attack ===<br />
<br />
This script demonstrates a standard 5E D&D melee weapon attack, including detection of misses, fumbles, hits, and critical hits. If installed, alterbars is used to decrement the target's BAR3 value by the damage dealt.<br />
<br />
[[File:ScriptCards Longsword.png|Longsword Script Output]]<br />
<br />
<pre><br />
!scriptcard {{<br />
--#title|Longsword<br />
--#leftsub|Melee Attack<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
--#emoteText|@{selected|token_name} attacks @{target|token_name}<br />
--=TargetAC|@{target|npc_ac}<br />
--?[$TargetAC.Total] -gt 0|DoneWithAC<br />
--=TargetAC|@{target|ac}<br />
--:DoneWithAC|<br />
--=AttackRoll|1d20 + @{selected|strength_mod} [STR] + @{selected|pb} [PROF]<br />
--+Attack|@{selected|token_name} rolls [$AttackRoll] vs AC [$TargetAC].<br />
--?[$AttackRoll.Base] -eq 20|Crit<br />
--?[$AttackRoll.Base] -eq 1|Fumble<br />
--?[$AttackRoll.Total] -ge [$TargetAC.Total]|Hit<br />
--+Miss|The attack missed.<br />
--^Final|<br />
<br />
--:Fumble|<br />
--+Fumble!|The attack went horribly wrong.<br />
--^Final|<br />
<br />
--:Hit|<br />
--=Damage|1d8 + @{selected|strength_mod} [STR]<br />
--+Hit!|The attack hit @{target|token_name} for [$Damage] slashing damage.<br />
--@alter|_target|@{target|token_id} _bar|3 _amount|-[$Damage]<br />
--^Final|<br />
<br />
--:Crit|<br />
--=Damage|1d8 + @{selected|strength_mod} [STR] + 1d8 [CRIT]<br />
--+Critical Hit!|The attack hit @{target|token_name} for [$Damage] slashing damage.<br />
--@alter|_target|@{target|token_id} _bar|3 _amount|-[$Damage]<br />
<br />
--:Final|<br />
}}<br />
</pre><br />
<br />
==== How it Works ====<br />
<br />
In lines 1-5, we set the title, subtitle, and emote text along with the tokens for the emote area.<br />
<br />
Lines 6-9 allow us to determine the AC of the target. On the 5E Roll20 sheet, NPCs armor class is stored in "npc_ac", while PCs armor class is in "ac". First we grab npc_ac and if it is zero, we check AC.<br />
<br />
Line 10 rolls the attack roll, rolling 1d20 and adding the attacker's strength modifier and proficiency bonus<br />
<br />
Line 11 displays the result of the attack roll on the card<br />
<br />
Lines 12-14 determine what kind of result the attack had. If the .Base value of the roll was 20, we branch to "Crit". If it was 1, we branch to "Fumble". If the .Total value of the roll was greater than or equal to the AC that was determined in Lines 6-9, we branch to Hit.<br />
<br />
Assuming we didn't branc anywhere, the result of the attack was a miss, so we display that on line 15 and then branch to "Final"<br />
<br />
This is followed by three branch segments, :Fumble, :Hit, and :Crit. A fumble displays a text message and branches to :Final.<br />
<br />
On a hit or a crit, we roll Damage (adding additional damage dice on a crit). We display a "Hit!" or "Critical Hit!" message and then make an API call to AlterBars, passing it the token id, bar we want to modify (3 in this case), and the amount we want to modify by the Damage value.<br />
<br />
=== Party Health Status ===<br />
<br />
This example calculates the current Hit Points remaining and HP percentage for each character and creates a color-coded display with the current party status.<br />
<br />
[[File:ScriptCards Party Health.png]]<br />
<br />
<pre><br />
!scriptcard {{<br />
--#title|Party Status<br />
--#titleCardBackground|#33CC33<br />
--#oddrowbackground|#bfee90<br />
--#evenrowbackground|#90eebf<br />
-->HealthCheck|@{Quej Grastra|character_id}<br />
-->HealthCheck|@{Brim Cheuto|character_id}<br />
-->HealthCheck|@{Odug Ututees|character_id}<br />
--X|End of card Execution<br />
<br />
--:HealthCheck|<br />
--=HealthPerc|[*[%1%]:hp] / [*[%1%]:hp^] * 100 \ 1<br />
--=HealthColor|000000<br />
--?[$HealthPerc.Total] -gt 50|HealthSkip<br />
--=HealthColor|FF0000<br />
--:HealthSkip|<br />
--+[*[%1%]:character_name]|has [#[$HealthColor.RollText]][*[%1%]:hp] of [*[%1%]:hp^][/#] HP [R]([$HealthPerc.Total]%)[/R]<br />
--<|End of HealthCheck<br />
}}<br />
</pre><br />
<br />
==== How it Works ====<br />
<br />
Lines 1-4, we set the card title, and set the title background and row background colors to shades of green.<br />
<br />
Lines 5-7 make gosub calls the the "HealthCheck" subroutine, passing in the character ID of each of the named characters (these are the names of the characters in my test game)<br />
<br />
Line 8 terminates the script execution.<br />
<br />
The remaining lines of the script are the HealthCheck subroutine, which works like this:<br />
<br />
Line 10 is the subroutine label (:HealthCheck)<br />
<br />
Line 11 uses the character id passed as a parameter and combines it with character attribute lookup *(...) to retrieve the value of "hp" and "hp<nowiki>^</nowiki>" for the character. The <nowiki>^</nowiki> character is used to specify that we want the MAX value for this attribute for the second call. We divide these two numbers and multiple by 100 to get a percentage. Finally, we use integer division by 1 to round the percentage and drop the decimals. The end result gets stored in the HealthPerc roll variable.<br />
<br />
Line 12 defaults to color of the health text to black<br />
<br />
Line 13 check to see if the health percentage is greater than 50. If so, it branches to HealthSkip, preventing the script from executing line 13.<br />
<br />
Line 14 sets the color of the health text to red<br />
<br />
Line 15 is the label that will be branched to from Line 13 to skip the red coloring<br />
<br />
Line 16 again uses character attribute substitution and the passed parameter value to output a display line containing the character name, the colorized health total, and the percentage value. The percentage is right-justified.<br />
<br />
Line 17 returns from the HealthCheck subroutine.<br />
<br />
=== Expanded Magic Missile Script ===<br />
<br />
This is the expanded and enhanced version of the Magic Missile script covered in {{yt|watch?v=u50xvNzS9Zk | this video}}. It includes visual and audio effects, checking and deducting spell slots, and applying damage using either Token-Mod or Alterbars.<br />
<br />
<pre><br />
!scriptcard {{ <br />
--#title|Magic Missile<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
<br />
-->GetAndCheckSlotInformation|<br />
<br />
--=MissileCount|[$SlotLevel] + 2<br />
--=DisplayCount|1<br />
--=MissileDamage|0<br />
--#leftsub|Slot level [$SlotLevel]<br />
--#rightsub|Ranged Attack<br />
--#emoteText|@{selected|character_name} uses a level [$SlotLevel.Total] spell slot to fire [$MissileCount.Total] missiles of magical force!<br />
<br />
--:MissileLoop|<br />
-->FireMissile|<br />
--=DisplayCount|[$DisplayCount] + 1<br />
--?[$DisplayCount] -le [$MissileCount]|MissileLoop<br />
--+Total|Total damage is [$MissileDamage]<br />
-->DeductSpellSlot|<br />
--#rightsub|Level [$SlotLevel] Left: [$SlotsRemaining] <br />
-->PlayEffects|none;burst-smoke;beam-magic;spell_01<br />
-->ApplyDamageTokenmod|@{target|token_id};3;-[$MissileDamage]<br />
-->ApplyDamageAlterbars|@{target|token_id};3;-[$MissileDamage]<br />
--X|<br />
<br />
--:FireMissile|<br />
--=ThisMissile|1d4 + 1<br />
--=MissileDamage|[$MissileDamage] + [$ThisMissile]<br />
--+Missile|[$DisplayCount.Total] Hits for [$ThisMissile] [b]force[/b] damage<br />
--<|<br />
<br />
--:GetAndCheckSlotInformation|<br />
--=SlotLevel|?{Spell Slot Level?|1|2|3|4|5|6|7|8|9}<br />
--=SlotsTotal|[*S:lvl[$SlotLevel]_slots_total]<br />
--=SlotsExpended|[*S:lvl[$SlotLevel]_slots_expended]<br />
--?[$SlotsExpended.Total] -ge [$SlotsTotal.Total]|NoSlotsLeft<br />
--<|<br />
<br />
--:NoSlotsLeft|<br />
--+|[*S:character_name] has no level [$SlotLevel.Total] spell slots available.<br />
--X|<br />
<br />
--:DeductSpellSlot|<br />
--=SlotsExpended|[$SlotsExpended] + 1<br />
--@setattr|_charid [*S:character_id] _lvl[$SlotLevel]_slots_expended|[$SlotsExpended] _silent<br />
--=SlotsRemaining|[$SlotsTotal] - [$SlotsExpended]<br />
--<|<br />
<br />
--:PlayEffects|Parameters are : source effect; target effect; line effect; sound effect<br />
--vtoken|@{selected|token_id} [%1%]<br />
--vtoken|@{target|token_id} [%2%]<br />
--vbetweentokens|@{selected|token_id} @{target|token_id} [%3%]<br />
--@roll20AM|_audio,play,nomenu|[%4%]<br />
--<|<br />
<br />
--:ApplyDamageTokenmod|Parameters are tokenid;bar#;amount<br />
--@token-mod|_ignore-selected _ids [%1%] _set bar[%2%]_value|[%3%]<br />
--<|<br />
<br />
--:ApplyDamageAlterbars|<br />
--@alter|_target|[%1%] _bar|[%2%] _amount|[%3%]<br />
--<|<br />
}}<br />
</pre><br />
<br />
===Hidden Roll===<br />
<br />
A roll where only the GM sees the result of the roll.<br />
[[File:Scriptcards-hiddenroll.png|right]]<br />
<pre><br />
!script {{<br />
--#title|Stealth Check<br />
--=Roll|1d20 + @{selected|stealth}<br />
--+|@{selected|token_name} attempts to move undetected...<br />
--*GMLine|@{selected|token_name} rolled a [$Roll]<br />
}}<br />
</pre><br />
<br />
===Elsewhere===<br />
* {{fpl|10000297/ Scritpcard API Working and Sharing}}<br />
* [https://gist.github.com/dubzilla1/cba439bd1f47ecdd81d0c79a482c4a91 Pathfinder 2E heal macros]<br />
<br />
[[Category:Featured articles]]<br />
[[Category:Macros]]<br />
[[Category:API Commands]]</div>5004103https://wiki.roll20.net/Script:ScriptCardsScript:ScriptCards2022-02-13T13:39:38Z<p>5004103: /* Assign Variable to Built-In Function (--~) */</p>
<hr />
<div>{{revdate}}<br />
== Introduction ==<br />
'''ScriptCards''' provides a script interpreter that can be used to create powerful macros that display the results of player/NPC actions, or display other information in a pleasing visual format in your game's {{Text Chat}}. The scripting language contains variables (both dice-roll (enhanced numerics) and strings) as well, conditionals, branching, subroutines with parameters, and a set of built-in functions to simplify working with Roll20 information.<br />
{{script overview<br />
|name=ScriptCards<br />
|author=[[Kurt J.]]<br />
|code=ScriptCards<br />
|version=1.4.10<br />
|lastmodified=2021-12-04}}<br />
ScriptCards is not game-system specific, and can be used with any system/sheet. Near the end of this Wiki there is a section set aside for libraries that can implement system-specific tasks, with the hope that enthusiasts playing particular systems will create and share utility functions that can be utilized by the wider community.<br />
<br />
The default display style for ScriptCards output is similar to the format used to document player and NPC abilities in Dungeons and Dragons 4th Edition, but does not have any system ties to D&D4E.<br />
<br />
Current OneClick Version : 1.4.10<br />
'''''Note:''''' '''As of 2021-12-04, ScriptCards 1.4.10 has been submitted for OneClick update. The documentation below is in the process of being updated for 1.4.10.<br />
<br />
Current Development Version : 1.5.2<br />
<br />
'''''<big>Critically Important: ScriptCards does not use/parse [[Inline|inline rolls]]. ScriptCards includes its own built-in dice roll parser to allow for the use of variables inside dice rolls. As of version 1.2.3, ScriptCards will now take inline rolls and substitute the total result value in statement strings, meaning that you can utilize inline rolls but ScriptCards will only see the result of the roll, and not parse the roll components itself.</big>'''''<br />
{{#evp:youtube|hyR7Jnq4mQM|[[Script:ScriptCards|ScriptCards]] Introduction|right|650}}<br />
* {{fpl|9752053/ ScriptCards thread}}<br />
** {{fpl|10000297/ Scritpcard API Working and Sharing}}<br />
* {{repo|kjaegers/ScriptCards/tree/main/ScriptCards_API ScriptCards_API}} - GitHub repository for source before the one-click version is updated.<br />
* {{repo|kjaegers/ScriptCards/tree/main/ScriptExamples ScriptCards Samples}} - Branch of the GitHub repo that contains sample scripts.<br />
* https://discord.gg/jSB4wTNpXb - Discord Channel<br />
* {{yt.be|hyR7Jnq4mQM ScriptCards Intro}} 45min, Jan 2021<br />
* {{yt.be|u50xvNzS9Zk ScriptCards Magic Missile Deep Dive}} 39min, Feb 2021<br />
__TOC__<br />
=== Is ScriptCards Related to [[PowerCards]]? ===<br />
<br />
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.<br />
<br />
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 ({{code|name}}, {{code|leftsub}}, {{code|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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
Check the '''[[#What to Know if you are Coming from PowerCards|What to Know if you are Coming from PowerCards]]'''-section for a comparison table between the two scripts.<br />
<br />
=== What is a ScriptCard Script ===<br />
<br />
A ScriptCard Script is text written into the {{Text Chat}} (either typed directly, pasted, or run via a macro) that will produce a card of information in the [[Text Chat|chat window]]. A ScriptCard Script is composed of an [[API]] command: <code><nowiki>!scriptcard {{ }}</nowiki></code> enclosing any number of lines that determine the output that will be added to the card. At it simplest, the following macro:<br />
<br />
<pre>!scriptcard {{ }}</pre><br />
<br />
Will produce just a title card that displays “ScriptCards” as the name:<br />
<br />
[[File:Scriptcard blank.png]]<br />
<br />
Of course, this is just the simplest type of macro and isn’t very useful. In order to produce useful output, we need to include lines between the <code><nowiki>{{</nowiki></code> and <code><nowiki>}}</nowiki></code> that direct the API script as to what it should do.<br />
<br />
== Structure of a ScriptCard Line ==<br />
<br />
All ScriptCard lines begin with two dashes, followed by an ''statement identifier character'' that lets ScriptCards what type of line it is. There are several of these, and they are detailed in the next section. After the line type identifier, a Tag name 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.<br />
<br />
Following the Tag is a vertical bar, and then the content of the line itself. Again, each type of line might interpret this content differently.<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Identifier !! Statement Type !! Tag !! Content !! Notes<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--/</nowiki> || Comment || unused || unused || The <code>--/</code> 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--#</nowiki> || 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").<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--+</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--=</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--&</nowiki> || Assign String 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. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--@</nowiki> || 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 (i.e., [[TokenMod|!token-mod]], or [[ChatSetAttr|!setattr]], etc.)<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--:</nowiki> || 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<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--^</nowiki> || Branch To || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--></nowiki> || Call Procedure || 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<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--<</nowiki> || 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.<br />
|- <br />
| style="white-space:nowrap" | <nowiki>--?</nowiki> || Conditional Branch || Condition to be evaluated || True Branch Label<nowiki>|</nowiki>False Branch Label || The condition will be evaluated and execution will jump to one of the two indicated branches (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 included a semicolon separated list of parameters. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--s</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--l</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--v</nowiki> || 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+'''''<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--a</nowiki> || Play Audio Track || Unused || Jukebox track name (case sensitive) || Plays an audio track by name from the Roll20 jukebox. '''''Requires v1.5.2+'''''<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--e</nowiki> || Echo to Chat || Name to send chat command as || Chat message to send || Variable substitution takes place on the tag and content.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--R</nowiki> || Retrieve Repeating Section Row information || "find", "first", or "next" || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--~</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--c</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--i</nowiki> || Information Request || User Prompt;Button Caption || InfoType;VariableName;ParameterText || See full documentation below.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--d</nowiki> || 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. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--%</nowiki> || 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. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--*</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--!</nowiki> || Object Modification || <objectType>:<objectId> || setting:value|setting:value|setting:value... || Set properties of tokens/characters or character attributes ('''''v1.5.0+ required''''')<br />
|}<br />
<br />
== ScriptCard Statement Type Details ==<br />
The sections below detail the individual statement types supported by ScriptCards<br />
<br />
=== Comment (--/) ===<br />
<br />
A --/ statement is ignored by the ScriptCards parser. You can use this type of statement to add comments and informational text to your script. <br />
<br />
Example:<br />
<pre><br />
!script {{<br />
--/|Script Name : Fireball<br />
--/|Purpose : Allow the player to cast a fireball and blow stuff up!<br />
.<br />
.<br />
.<br />
}}<br />
</pre><br />
<br />
=== Set Parameter (--#) ===<br />
<br />
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.<br />
<br />
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.<br />
<br />
'''''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.'''''<br />
<br />
Examples:<br />
<pre><br />
--#title|Magic Missile<br />
--#leftsub|Level 1 Spell<br />
--#rightsub|Force Damage<br />
</pre><br />
<br />
The three examples above set the “title”, “leftsub”, and “rightsub” values for the card to the content value for the line. <br />
<br />
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.<br />
Settings Lines do not produce output lines on the card.<br />
<br />
The following settings are available (note that parameter names are ''not'' case sensitive):<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Name !! Effect/Use !! Default Value !! Type<br />
|-<br />
| 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<br />
|-<br />
| allowplaintextinrolls || If set to a non-zero value, plain character text in rolls will be copied to the roll text || 0 || Per-Line<br />
|-<br />
| bodyFontFace || Name of the font used in the card rows || Helvetica || Global<br />
|-<br />
| bodyFontSize || Size of the text in the card rows || 14px || Global<br />
|-<br />
| bodybackgroundimage || Specify an image (content for a CSS background-image tag) for the body area || none || Global<br />
|-<br />
| buttonBackground || Background color for buttons created with [button][/button] || #1C6EA4 || Per-Line<br />
|-<br />
| buttonBackgroundImage || A CSS specifier for a background image to use for buttons (i.e. url(...);) || empty || Per-Line<br />
|-<br />
| buttonBorderColor || Border (outline) color for buttons created with [button][/button] || #999999 || Per-Line<br />
|-<br />
| buttonFontFace || Font Family specifier for captions on buttons created with [button][/button] || Tahoma || Per-Line<br />
|-<br />
| buttonFontSize|| Text size for captions on buttons created with [button][/button] || x-small || Per-Line<br />
|-<br />
| buttonTextColor|| Text color of labels on buttons created with [button][/button] || #FFFFFF || Per-Line<br />
|-<br />
| 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<br />
|-<br />
| deferralcharacter || Changes the meta script deferral sequence to the specified value || ^ || Per-Line<br />
|-<br />
| diceFontColor|| Color of the dice created with the [d4] [d6], etc. formatting markers || #1C6EA4 || Per-Line<br />
|-<br />
| dicefontsize || Size of the dice created with the [d4] [d6], etc. formatting markers || 3.0em || Per-Line<br />
|-<br />
| 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<br />
|-<br />
| disablerollprocessing || If set to a non-zero value, --= lines will not process dice rolls strings || 0 || Per-Line<br />
|-<br />
| emoteBackground || Background color of the emote area || #f5f5ba || Global<br />
|-<br />
| emoteFont || Name of the font used in emote area (above the title of the output card) || Georgia || Global<br />
|-<br />
| emoteFontColor || Color of the font in the emote area || None (Empty) || Global<br />
|-<br />
| emoteFontSize || Size of the font used in the emote area || 14px || Global<br />
|-<br />
| emoteFontWeight || Font weight for the font in the emote area || bold|| Global<br />
|-<br />
| emoteState || If set to anything other than "visible", the emote portion of the card will not be displayed || visible || Global<br />
|-<br />
| emoteText || Text to display in the emote portion of the card || None (Empty) || Global<br />
|-<br />
| emotefont || Name of the font used in the emote text area || font-family: Georgia, serif; font-weight: bold; || Global<br />
|-<br />
| evenRowBackground || Hex code for the background color for even rows || #eeeeee || Per-Line<br />
|-<br />
| evenRowFontColor || Hex code for the text color for even rows || #000000 || Per-Line<br />
|-<br />
| evenrowbackgroundimage || Specify an image (content for a CSS background-image tag) for the even card rows || none || Per-Line<br />
|-<br />
| executionlimit || Maximum number of script lines the interpreter will try to execute. This prevents "infinite loop" sandbox crashes || 40000 || Global<br />
|-<br />
| hideCard || If set to any non-default value, the entire card output will be suppressed || 0 || Global<br />
|-<br />
| 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<br />
|-<br />
| 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<br />
|-<br />
| lineheight || Vertical size of each line on the output card || normal || Per-Line<br />
|-<br />
| nominmaxhighlight || If set to anything other than "0", rolls will not display crit/fumble/mixed highlight colors. || 0 || Per-Line<br />
|-<br />
| norollhighlight || If set to anything other than "0", rolls will not be formatted (plain numbers) but will still get a tooltip with details ('''''v1.3.6b+''''') || 0 || Per-Line<br />
|-<br />
| oddRowBackground || Hex code for the background color for even rows || #d0e4f5 || Per-Line <br />
|-<br />
| oddRowFontColor || Hex code for the text color for odd rows || #000000 || Per-Line<br />
|-<br />
| oddrowbackgroundimage || Specify an image (content for a CSS background-image tag) for the odd crd rows || none || Per-Line<br />
|-<br />
| reentrant || Used to name a script for rentrant button use || 0 || Global<br />
|-<br />
| 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)0 || Global<br />
|-<br />
| rollhilightcolorboth || Background box hilight color if both a 1 and a max on the die are rolled ('''''1.4.4+''''') || #8FA4D4 || Per-Line<br />
|-<br />
| rollhilightcolorcrit || Background box hilight color if the maximum number on the die was rolled ('''''1.4.4+''''') || #88CC88 || Per-Line<br />
|-<br />
| rollhilightcolorfumble || Background box hilight color if a 1 was rolled ('''''1.4.4+''''') || #FFAAAA || Per-Line<br />
|-<br />
| rollhilightcolornormal || Background box hilight color if neither a 1 or a max on the die are rolled ('''''1.4.4+''''') || #FFFEA2 || Per-Line<br />
|- <br />
| rollhilightlineheight || Determines the height of the hilight box placed around roll results ('''''1.4.2+''''') || 1.0em || Per-Line<br />
|-<br />
| roundUp || If set to a non-default value, integer division will round up instead of down || 0 || Per-Line<br />
|-<br />
| showfromfornonwhispers || If set to a non-zero value, will include the sender on cards that aren't whispered || 0 || Global<br />
|-<br />
| 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<br />
|-<br />
| subtitleFontColor || Color of the text in the subtitle areas || #FFFFFF || Global<br />
|-<br />
| subtitleFontFace || Name of the font used on the subtitle sections || Tahoma || Global<br />
|-<br />
| subtitleFontSize || Size of the subtitle font || 13px || Global<br />
|-<br />
| subtitleSeperator || The character(s) that will be placed between leftsub and rightsub || <nowiki>&#x2666</nowiki>; || Global<br />
|-<br />
| tableBorderRadius || CSS specifier for how rounded the borders of the output card are. Use "0px;" for square borders || 6px; || Global<br />
|-<br />
| tableShadow || CSS specifier for the drop shadow under the output card || 5px 3px 3px 0px #aaa; || Global<br />
|-<br />
| tablebgcolor || Background color of the whole card. '''''Normally not visible''''' || #EEEEEE || Global<br />
|-<br />
| tableborder || Color of the border that surrounds the whole card || 2px solid #000000; || Global<br />
|-<br />
| 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<br />
|-<br />
| timezone || IANA Specifier for the local time zone, used in system/date functions || America/New_York || Per-Line<br />
|-<br />
| title || Text displayed in the title area of the card || ScriptCards || Global<br />
|-<br />
| titleCardBackground || A hex color code representing the background color of the title area. || #1c6ea4 || Global<br />
|-<br />
| titleFontColor || Color of the text on the card title || #FFFFFF || Global<br />
|-<br />
| titleFontFace || Name of the font used on the title area || Contrail One || Global<br />
|-<br />
| titleFontLineHeight || Line spacing on the title area || 1.2em || Global<br />
|-<br />
| titleFontSize || Size of the title font || 1.2em || Global<br />
|-<br />
| titlecardbackgroundimage || Specify an image (content for a CSS background-image tag) for the title card area || none || Global<br />
|-<br />
| titlecardbottomborder || Border CSS specifier for the bottom of the title card area || 2px solid #444444; || Global<br />
|-<br />
| titlecardgradient || If set to non-zero value, will place a vertical gradient on the title card area || 0 || Global<br />
|-<br />
| usehollowdice || If set to a non-zero value, the hollow/outline versions of the dice fonts will be used || 0 || Per-Line<br />
|-<br />
| whisper|| Comma separated list of who to whisper the output to. Use "gm" for [[GM|GMs]] and "self" for the sender || none || Global|}<br />
|}<br />
<br />
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). <br />
<br />
''Setting Lines do not produce output lines on the card''<br />
<br />
=== Direct Output (--+) ===<br />
<br />
A direct output line display 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.<br />
<br />
Examples of Direct Output lines:<br />
<pre><br />
--+Hello|World<br />
--+Attack|The monster rolls [$Attack] to hit!<br />
--+Damage|@{target|token_name} is hit for [$Damage] [#3333AA][b]frost[/b][/#] damage.<br />
</pre><br />
<br />
Direct Output lines support inline formatting, roll variable replacement, character attribute references, and procedure variables.<br />
<br />
=== GM Output (--*) ===<br />
<br />
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. <br />
<br />
Example:<br />
<pre><br />
--+PlayerLine|This line is shown on the public card<br />
--*GMLine|This line will only be shown to GMs, on a separate card.<br />
</pre><br />
<br />
=== Roll Variable Assignment (--=) ===<br />
<br />
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.<br />
<br />
'''''All components of a roll equation should be separated with spaces.'''''<br />
<br />
Examples:<br />
<pre><br />
--=MissileDamage|1d4 + 1<br />
--=Attack|1d20 + @{selected|strength_mod} [STR] + @{selected|pb} [PROF]<br />
</pre><br />
<br />
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. Text enclosed in square brackets ([]) is considered "flavor text" and will be added to the result text but does not impact the roll result.<br />
<br />
The following dice formats are supported:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Format Pattern !! Example !! Description<br />
|-<br />
| XdY || 3d8 || Simple format. Roll a Y-sided die X times<br />
|-<br />
| XdYkhZ || 2d20kh1 || Roll Y-sided die X times and keep the highest Z number of dice<br />
|-<br />
| XdYklZ || 4d6kl3 || Roll Y-sided die X times and keep the lowest Z number of dice <br />
|-<br />
| XdY>Z || 5d6>3 || Roll Y-sided die X times and count a 1 for each roll greater than Z <br />
|-<br />
| XdY<Z || 5d6<3 || Roll Y-sided die X times and count a 1 for each roll less than Z <br />
|-<br />
| 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<br />
|-<br />
| 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<br />
|-<br />
| 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)<br />
|-<br />
| 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<br />
|-<br />
| 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).<br />
|-<br />
| 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.<br />
|-<br />
| 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. ('''''v1.5.1''''')<br />
|}<br />
<br />
The following operators are supported in a roll equation:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Operator !! Operation<br />
|-<br />
| + || Addition <br />
|-<br />
| - || Subtraction <br />
|-<br />
| * || Multiplication <br />
|-<br />
| / || Division <br />
|-<br />
| \ || Integer Division (Rounds down) <br />
|-<br />
| % || Modulo (Remainder of Divison)<br />
|}<br />
<br />
Roll Variables can be accessed at any time after they have been created by using the [$VariableName] format, with the following optional modifiers:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Modifier !! Meaning<br />
|-<br />
| No modifier || In a Direct Output Line (<nowiki>--+</nowiki>) 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<br />
|-<br />
| .Total || The end result of the roll equation as an unformatted number <br />
|-<br />
| .Base || The cumulative result of any dice rolled in the Roll Text (Numeric modifiers are not included) <br />
|-<br />
| .Ones || The number of dice in the roll that came up as 1s <br />
|-<br />
| .Aces || The number of dice in the roll that came up as the maximum number on the die <br />
|-<br />
| .Odds || The number of dice in the roll that came up with an odd number <br />
|-<br />
| .Evens || The number of dice in the roll that came up with an even number <br />
|-<br />
| .RollText || The raw text of the roll that was use to generate the results <br />
|-<br />
| .Text || A text representation of the results of the roll, including the numbers rolled for each die <br />
|-<br />
| .tableEntryText || The text portion of the result of a table roll<br />
|-<br />
| .tableEntryImgURL || The image source portion of the result of a table roll<br />
|-<br />
| .tableEntryValue || Numeric value of tableEntryText (via parseInt). If a non-numeric value, will be 0<br />
|-<br />
| .Raw || The total numeric result without any formatting, even if placed somewhere formatting would normally be done. <br />
|}<br />
<br />
Examples:<br />
<pre><br />
--+Total Damage|[$MissileDamage.Total] (roll was 1d4+1)<br />
--+Base Damage|[$MissileDamage.Base] (without the +1)<br />
--=Attack|1d20 + @{selected|strength_mod} [STR] + @{selected|pb} [PROF] + [$BlessBonus] [Bless]<br />
</pre><br />
<br />
In this case, 1d4 will be rolled and stored in “BlessBonus”, which can then be used in the Attack line.<br />
<br />
'''''Mathematical Functions in Roll Expressions '''''<br />
<br />
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:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Expression !! Meaning<br />
|-<br />
| {ABS} || Absolute Value<br />
|-<br />
| {CEIL} || Ceiling value (round up to the next whole number)<br />
|-<br />
| {FLOOR} || Floor value (round down to the next whole number)<br />
|-<br />
| {ROUND} || Round value (round up if the decimal portion is greater than 0.5, otherwise round down) '''Note: As of 1.4.11, ROUND now supports :X as a suffix to round to a given number of decimal places (ie, {ROUND:2}'''<br />
|-<br />
| {NEGATE} || Multiply the value by negative one.<br />
|-<br />
| {SQRT} || Take the square root of the running value.<br />
|-<br />
| {SQUARE} || Square the running value.<br />
|-<br />
| {CUBEROOT} || Take the cube root of the running value.<br />
|-<br />
| {CUBE} || Cube the running value.<br />
|-<br />
| {SIN} || Return the SIN of running value.<br />
|-<br />
| {COS} || Return the COS of running value.<br />
|-<br />
| {TAN} || Return the TAN of running value.<br />
|-<br />
| {ASIN} || Return the ASIN of running value.<br />
|-<br />
| {ACOS} || Return the ACOS of running value.<br />
|-<br />
| {ATAN} || Return the ATAN of running value.<br />
|-<br />
| {MAX:X} || Caps the running value at X. ('''''v1.4.12''''')<br />
|-<br />
| {MIN:X} || If the running value is less than X, set the value to X. ('''''v1.4.12''''')<br />
|-<br />
| {CLAMP:X:Y} || Adjust the running value to remain between X (lower bound) and Y (upper bound) ('''''v1.4.12''''')<br />
|}<br />
<br />
Here are the syntax rules when using the above listed functions:<br />
<br />
Example 1.<br />
<br />
<pre><br />
!script {{<br />
--=output|2.9 {FLOOR}<br />
--+output|[$output]<br />
}}<br />
</pre><br />
<br />
The output from this example is "2".<br />
<br />
Example 2.<br />
<br />
<pre><br />
!script {{<br />
--=output|2.9 {FLOOR} {NEGATE} - 3<br />
--+output|[$output]<br />
}}<br />
</pre><br />
<br />
The output from this example is "-5".<br />
<br />
Basically, a function will use as its input whatever the current "running total" is.<br />
<br />
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.<br />
<br />
<br />
'''''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 <nowiki>[[ ]]</nowiki> 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.<br />
<br />
'''''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.<br />
<br />
'''Rolling on Rollable Tables'''<br />
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.<br />
<br />
''Roll Variable Lines do not produce output lines on the card.''<br />
<br />
=== String Variable Assignment (--&) ===<br />
<br />
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:<br />
<br />
<pre><br />
--&MyText|Hello<br />
</pre><br />
<br />
Here, we assign the text "Hello" to the string variable named MyText. You can also append text to a string variable by prefixing the content with a + sign:<br />
<br />
<pre><br />
--&MyText|+ World<br />
</pre><br />
<br />
If run after the statement above, MyText will now contain "Hello World".<br />
<br />
String variables can be referenced using the syntax [&variablename]<br />
<br />
=== Call API (--@) ===<br />
<br />
ScriptCards can use a Call API instruction to execute other API commands. The Tag contains the API 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 API command is executed.<br />
<br />
Examples:<br />
<pre><br />
--@eh|list<br />
--@alter|_target|@{target|token_id} _bar|3 _amount|-[$Damage]<br />
</pre><br />
<br />
In the first example above, the command <code>!eh list</code> will be executed, calling [[EncounterHelper]]. In the second, {{fpl|1216260/ AlterBars}} is called to modify a token's Bar 3 value.<br />
<br />
'''''Note:''''' When ScriptCards (or any API script) runs other API 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).<br />
<br />
See [[API:Script Index]] for more options.<br />
<br />
=== Branch Label (--:) ===<br />
<br />
A branch label defines a line in your code that can be reached by one of the branching instructions (<nowiki>--^</nowiki>, <nowiki>--></nowiki>, or <nowiki>--?</nowiki>). The Tag serves as the label name, and must be unique on the card.<br />
<br />
The vertical bar (|) separator must be present, but the content portion of the line is unused and can be treated as a comment.<br />
<br />
Examples:<br />
<pre><br />
--:MyLoop|<br />
--:CriticalHit|Will jump here if we roll a critical hit!<br />
</pre><br />
<br />
''A Branch Label line does not produce an output line on the card.''<br />
<br />
=== Branch (--^) === <br />
<br />
A Branch line 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.<br />
<br />
Examples:<br />
<pre><br />
--^MyLoop|Jumps to MyLoop<br />
--^SkipCrit|We didn't crit, so skip the Crit code<br />
</pre><br />
<br />
''A Branch line does not produce an output line on the card.''<br />
<br />
=== Call Procedure (-->) ===<br />
<br />
Similar to a branch, a Call Procedure (sometimes knows 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 (<nowiki>--<</nowiki>) 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 (;).<br />
<br />
Examples:<br />
<pre><br />
-->FixFormat|#3333FF;#999999<br />
</pre><br />
<br />
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%].<br />
<br />
=== Return (--<) ===<br />
<br />
A return instruction marks the end of a Gosub procedure. 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.<br />
<br />
Examples:<br />
<pre><br />
--<|<br />
--<|End of MySub<br />
</pre><br />
<br />
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.<br />
<br />
=== Conditional Statement (--?) ===<br />
<br />
A conditional statement contains some equation in the Tag that will be evaluated. '''''If any part of the comparison can/does contain a space, it needs to be surrounded by double quotes'''''<br />
<br />
Based on the true/false result of the evaluation, one of two execution paths will be taken. These execution paths are detailed in the content section of the statement. The "if true" path is specified first (directly after the vertical bar), and the "if false" path is specified after it, also separated by a vertical bar.<br />
<br />
Example:<br />
<pre><br />
--?[$AttackRoll.Total] -ge [$TargetAC]|Hit|Miss<br />
</pre><br />
<br />
'''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.'''<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Branch Format !! Meaning<br />
|-<br />
| Label || If just a label is specified, execution will branch to that label when the comparison is matched.<br />
|-<br />
| >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 <br />
|-<br />
| =VariableName || The roll variable "VariableName" will be assigned the value following a semicolon (for example, the code "=Roll;1d20" will assign the value "1d20" to a variable named "Roll", if the condition is true).<br />
|-<br />
| &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).<br />
|-<br />
| % or %! || The current for...next loop will perform the "next" action (%) or will break out (%!) <br />
|-<br />
| [ || Code block (see below)<br />
|}<br />
<br />
Examples:<br />
<pre><br />
--?[$AttackRoll.Base] -eq 20|CriticalHit<br />
--?[$AttackRoll.Base] -eq 1|>Fumble;@{selected|dexterity_mod}<br />
--?"@{target|npc_type}" -inc "undead"|&MonsterType;Undead|&MonsterType;Not Undead<br />
--?[$Attack.Total] >= [$ArmorClass]|>Hit|>Miss<br />
</pre><br />
<br />
In the first example, if the Base value of AttackRoll is a 20 (natural 20 on the die) execution will branch to the CriticalHit label.<br />
<br />
In the second example, 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%].<br />
<br />
The third example looks for the word "undead" in the npc_type attribute of the targeted character. If it exists in the text, the MonsterType string variable will be set to "Undead", otherwise it will be set to "Not Undead". <br />
<br />
The final example would call 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.<br />
<br />
''Text that does/may contain a space should be enclosed in double quotes.''<br />
<br />
The following comparison operators are available:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Comparator !! Meaning<br />
|-<br />
| -eq || Equal To <br />
|-<br />
| -eqi || Case insensitive Equal To <br />
|-<br />
| -ne || Not Equal To <br />
|-<br />
| -nei || Case insensitive Not Equal To <br />
|-<br />
| -gt || Greater Than <br />
|-<br />
| -ge || Greater Than or Equal To <br />
|-<br />
| -lt || Less Than <br />
|-<br />
| -le || Less Than or Equal To <br />
|-<br />
| -inc || Includes (text strings). <br />
|-<br />
| -ninc || Does Not Include (text strings). <br />
|}<br />
<br />
Multi-part conditionals are supported with -and and -or as separators. For example:<br />
<br />
<pre><br />
--?[$Attack.Total] -ge @{target|npc_ac} -and [$Attack.Base] -ne 20|HitButNotCrit<br />
</pre><br />
<br />
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):<br />
<br />
true AND false OR true<br />
<br />
Will be evaluated as true. The first two (true and false) will be false, but then false OR true will be true.<br />
<br />
Conversely:<br />
<br />
true or false and false<br />
<br />
Will be false, because the first true and false will evaluate to true, and then true and false will be false.<br />
<br />
'''CODE BLOCKS'''<br />
<br />
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.<br />
<br />
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:<br />
<br />
<pre><br />
!script {{<br />
--=Roll|1d2<br />
--+Roll|[$Roll]<br />
--?[$Roll.Total] -eq 2|[<br />
--&Value|Yep!<br />
--+|We are inside the TRUE portion of the block<br />
--]|[<br />
--&Value|Nope<br />
--+|We are inside the FALSE portion of the block<br />
--]|<br />
--+After|the blocks!<br />
--+Value|[&Value]<br />
}}<br />
</pre><br />
<br />
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 --]|. <br />
<br />
At this time, blocks cannot be nested, and can only be created as part of a conditional (--[ is not a valid statement type)<br />
<br />
''A conditional statement does not produce a line of output on the card.''<br />
<br />
=== Case Statement (--c) ===<br />
<br />
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 (:). Each match condition includes a branch label that will be used if the test value matches the item. 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:<br />
<br />
<pre><br />
!script {{<br />
--#title|Case Statement Testing<br />
--=Roll|1d4<br />
--C[$Roll.Total]|1:>One;[$Roll]|2:>Two;[$Roll]|3:>Three;[$Roll]|4:>Four;[$Roll]<br />
--X|<br />
<br />
--:One| --+Value|was One ([%1%]) --<|<br />
--:Two| --+Value|was Two ([%1%]) --<|<br />
--:Three| --+Value|was Three ([%1%]) --<|<br />
--:Four| --+Value|was Four ([%1%]) --<|<br />
}}<br />
</pre><br />
<br />
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 variable as a parameter.<br />
<br />
=== Save and Load (--s and --l) ===<br />
<br />
This statement pair is used to either store (--s) or load (--l) data from persistent storage. Items stored in persistent storage remain between card rolls and between Roll20 sessions. There are two types of data that can be stored: settings and roll variables. <br />
<br />
Examples:<br />
<br />
<pre><br />
--Ssettings|GreenStyle<br />
--Srollvariables|FirstCardVars<br />
</pre><br />
<br />
In this case, the tag for the statement determines what type of item is being saved (settings or rollvariables). When saving settings, all non-default settings are written to the named setting storage value. When Roll Variables are saved, all variables that currently exist will be saved to the named storage value.<br />
<br />
Loading stored items simply requires the same command with the --l statement type:<br />
<br />
<pre><br />
--Lsettings|GreenStyle<br />
--Lrollvariables|FirstCardVars<br />
</pre><br />
<br />
When loading settings, all stored settings will be applied to the current card settings. You can override settings by changing them after the load.<br />
<br />
When loading roll variables, the saved variables will be added to (or overwrite if they have the same name) any variables on the current card. This means it is safe to create roll variables before the load statement.<br />
<br />
'''Practical Uses'''<br />
The major intended use of persistent storage is for storing card formats for use in later scripts. For example, the following script:<br />
<br />
<pre><br />
!scriptcard {{<br />
--#titlecardbackground|#22CC22<br />
--#oddrowbackground|#cceecc<br />
--#evenrowbackground|#99ee99<br />
--Ssettings|@{selected|token_name}<br />
}}<br />
</pre><br />
<br />
Would save the titlecardbackground, oddrowbackground, and evenrowbackground settings to a saved list named after the selected token's name. When creating cards for that token to run later, you could include the line:<br />
<br />
<pre><br />
--Lsettings|@{selected|token_name}<br />
</pre><br />
<br />
To load all of the settings at once. By creating these setting sets for each character, you can specify a different color scheme for each character that can then be used in cards with a single formatting line.<br />
<br />
There is a supplemental ! command added to support saved settings:<br />
<br />
<pre><br />
!sc-liststoredsettings<br />
</pre><br />
<br />
Will produce a list of all stored setting names, with buttons to list the setting values stored in each group and a button to delete groups as needed.<br />
<br />
=== Visual Effects (--v) ===<br />
<br />
The --v statement can be used to create visual effects on the tabletop. The tag portion of the statement can be either "token" or "betweentokens". The content portion of the statement contains the required parameters for the effect generation, separated by spaces. If the effect is "none", no effect will be played. If any other value that doesn't match a Roll20 effect name will result in a burst-fire effect.<br />
<br />
For "token" effects, the parameters are the token id for the token the effect happens on, followed by the effect specifier.<br />
<br />
Example:<br />
<pre><br />
--vtoken|@{selected|token_id} burst-fire<br />
</pre><br />
<br />
For "betweentoken" effects, the parameters are the source token id, the target token id, and the effect specifier.<br />
<br />
Example:<br />
<pre><br />
--vbetweentokens|@{selected|token_id} @{target|token_id} beam-magic<br />
</pre><br />
<br />
'''''Version 1.2.8+'''''<br />
<br />
An additional effect specifier, "point" is available in 1.2.8+. This specifier allows you to create a visual effect at a designated X/Y pixel coordinate. Future updates will add custom-vfx support to this option. The parameters are the X and Y coordinates and the effect descriptor. As of version 1.2.9, you can also use custom effect specifiers with Point effects:<br />
<br />
<pre><br />
--vpoint|150 200 burst-fire<br />
</pre><br />
<br />
=== Audio Effects (--a) ===<br />
<br />
'''''Requires version 1.5.2+'''''<br />
<br />
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.<br />
<br />
<pre><br />
--a|SwordHitSound<br />
</pre><br />
<br />
No external APIs are required.<br />
<br />
=== Echo to Chat (--e) ===<br />
<br />
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.<br />
<br />
Example:<br />
<pre><br />
--eThe Ghost|/em hovers around @{selected|character_name}... BOO!<br />
</pre><br />
<br />
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).<br />
<br />
'''''Whispering'''''<br />
<br />
You can use the echo statement to send a whisper, but there's a trick to it. If you execute this code here:<br />
<br />
<pre><br />
--eThe Ghost|/w ExamplePlayerName Boo.<br />
</pre><br />
<br />
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.<br />
<br />
So, in conclusion, it's best to use something like this when you're sending a whisper:<br />
<br />
<pre><br />
!script {{<br />
--#hidecard|1<br />
--&sender|The Ghost<br />
--&receiver|ExamplePlayerName<br />
--&message|Boo.<br />
--e[&sender]|/w [&receiver] [&message]<br />
--eScriptCards|/w gm **Whispered from [&sender] to [&receiver]:** [&message] <br />
}}<br />
</pre><br />
<br />
This will ensure that the message appears in your chat feed as well.<br />
<br />
=== Repeating Section Access (--R) ===<br />
<br />
ScriptCards (as of v0.0.13) supports accessing repeating section rows on a character sheet (for example: the attacks, the items, and the repeating resources) with the --R statement type. <br />
<br />
There are three basic commands you can use with --R, and they are specified by <br />
the tag used:<br />
<br />
<br />
'''''The "find" tag'''''<br />
<br />
An Rfind statement is used to search through a repeating field. Here is the general form of such a statement.<br />
<br />
<pre><br />
--Rfind|characterid;EntryName;SectionPrefix;SearchField<br />
</pre><br />
<br />
This is the most direct way to access a repeating section row. Supplying the character ID, followed by what you are looking for (Greatsword, for example), followed by the character sheet's section prefix (repeating_attack), followed by the field to check what you are searching for (atkname) will load the matching section (if found) into the script parsers memory. For example:<br />
<br />
<pre><br />
--Rfind|@{selected|character_id};Greatsword;repeating_attack;atkname<br />
</pre><br />
<br />
Will look at the character's "repeating_attack" section for an entry with an atkname value equal to "Greatsword". Similarly:<br />
<br />
<pre><br />
--Rfind|@{selected|character_id};Bite;repeating_npcaction;name<br />
</pre><br />
<br />
Will look for a "Bite" action on an NPC's action list.<br />
<br />
<br />
'''''The "first" tag'''''<br />
<br />
<pre><br />
--Rfirst|characterid;section prefix<br />
</pre><br />
<br />
This form of the --R command will look at all of the entries in the specified repeating section and load the first one into memory:<br />
<br />
<pre><br />
--Rfirst|@{selected|character_id};repeating_attack<br />
</pre><br />
<br />
Would load the character's first "repeating_attack" row into memory.<br />
<br />
<br />
'''''The "next" tag'''''<br />
<br />
<pre><br />
--Rnext|<br />
</pre><br />
<br />
No parameters are required for --Rnext, which loads the next entry in the list that was obtained with "first" into memory.<br />
<br />
<br />
'''''Section prefixes and how to use them'''''<br />
<br />
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 open [[D&D 5E by Roll20|this page]], and search for the phrase "repeating sections".<br />
<br />
<br />
'''''Additional information'''''<br />
<br />
However a row is obtained, it will be parsed to replace any attribute references (ie, @{level}) with the corresponding character attribute.<br />
<br />
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".<br />
<br />
You can reference repeating attribute data using the syntax [*R:attributename] syntax (similar to referencing standard character attributes).<br />
<br />
Here are some examples:<br />
<br />
Display the details of the "Greatsword" PC attack:<br />
<br />
<pre><br />
!script {{<br />
--Rfind|@{selected|character_id};Greatsword;repeating_attack;atkname<br />
--+Attack Name|[*R:atkname]<br />
--+Base Damage|[*R:dmgbase]<br />
}}<br />
</pre><br />
<br />
[[File:Scriptcards repeating greatsword.png|Repeating Greatsword Attack]]<br />
<br />
List all of the actions an NPC can take (just actions, not legendary, etc.)<br />
<br />
<pre><br />
!script {{<br />
--#title|NPC Actions<br />
--#leftsub|@{selected|token_name}<br />
--Rfirst|@{selected|character_id};repeating_npcaction<br />
--:DisplayLoop|<br />
--?"[*R:name]" -eq NoRepeatingAttributeLoaded|Done<br />
--+Action:|[*R:name] [*R:attack_damage] [*R:attack_damagetype]<br />
--?"[*R:attack_damage2]" -eq ""|NoSecondaryDamage<br />
--+ |[*R:attack_damage2] [*R:attack_damagetype2]<br />
--:NoSecondaryDamage|<br />
--Rnext|<br />
-->DisplayLoop| <br />
--:Done|<br />
}}<br />
</pre><br />
<br />
[[File:Scriptcards repeating npcactions.png]]<br />
<br />
In the script above, we get the "first" repeating_npcaction and display information about it. We then execute "next" and repeat until we run into "NoRepeatingAttributeLoaded".<br />
<br />
See the section named [[#Repeating Section Values|Repeating Section Values]] for more information.<br />
<br />
<br />
'''''Special debugging command: dump'''''<br />
<pre><br />
--Rdump|<br />
</pre><br />
<br />
The "dump" command will list all of the attributes ScriptCards knows about for the currently loaded repeating row to the API Console Log.<br />
<br />
=== Assign Variable to Built-In Function (--~) ===<br />
<br />
ScriptCards has the ability to run a function built into the API script and return the results to a variable. Some functions return roll variables, while others return strings. See the function table below for details. The format is:<br />
<br />
--~VariableName|function;param1;param2;param3;...<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Function Name !! Parameters !! Description<br />
|-<br />
| distance || token_A_ID;token_B_ID || Calculate the Chebyshev distance in grid units between two tokens. This is the measurement scheme D&D 4E/5E use for diagonal distance measurement<br />
|-<br />
| euclideandistance || token_A_ID;token_B_ID || Calculate the Euclidean distance between two tokens. This is essentially the Pythagorean theorem in action. Returns the result in grid units.<br />
|-<br />
| euclideanpixel || token_A_ID;token_B_ID || Calculate the Euclidean distance between two tokens and returns the result is pixels instead of grid units. <br />
|-<br />
| euclideanlong || token_A_ID;token_B_ID || 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 is calculated instead of before. More accurate over long distances. <br />
|-<br />
| manhattandistance || token_A_ID;token_B_ID || Also called "taxicabdistance" (which is an acceptable function name), this measures to how-many-over, how-many-up/down distance, disallowing diagonal movement.<br />
|-<br />
| getselected || none || 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 the first selected token, VariableName2 the second, etc.<br />
|}<br />
<br />
'''''Functions with Sub Functions'''''<br />
<br />
Most ScriptCards functions are grouped into set as sub functions. The table below lists the major functions and their sub functions.<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Function Name !! Sub Function !! Parameters !! Return Type !! Description<br />
|-<br />
| array || define || arrayname;value1;value2;... || none || Creates an array called "arrayname" and adds value1, value2, etc. to the array<br />
|-<br />
| array || sort || arrayname || none || Sorts the specified array in place in ascending order (alphabetically)<br />
|-<br />
| array || numericsort || arrayname || none || Sorts the specified array in place in ascending order (numerically) ('''''v 1.4.10+ ''''')<br />
|-<br />
| array || add || arrayname;value1;value2;... || none || Adds value1, value2, ... to the existing array "arrayname"<br />
|-<br />
| array || remove || arrayname;value1;value2;... || none || Removes value1, value2, ... from the existing array "arrayname". Resets the array index to 0.<br />
|-<br />
| array || replace || arrayname;currentvalue;newvalue || none || Replaces all occurrences of "currentvalue" in "arayname" with "newvalue"<br />
|-<br />
| array || setatindex || arrayname;index;newvalue || none || Replaces the array item at index "index" with "newvalue"<br />
|-<br />
| array || getindex || arrayname || stringVariable || Retrieves the current index in "arrayname" and stores it in the supplied string variable<br />
|-<br />
| array || setindex || arrayname;newindex || none || Sets the current index in array "arrayname" to "newindex"<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| array || removeat || arrayname;indexposition || none || Removes the item at index "indexposition" from "arrayname". Resets the current array index to 0.<br />
|-<br />
| array || indexof || arrayname;searchvalue || stringVariable || Searches the array "arrayname" for and item with the value of "searchvalue" and, if found, returns the index of the first matching value or "ArrayError" if not found<br />
|-<br />
| array || getlength || arrayname || stringVariable || Returns the number of items in array "arrayname"<br />
|-<br />
| array || pagetokens || arrayname;tokenid;(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. 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.)<br />
|-<br />
| 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.<br />
|-<br />
| array || stringify || arrayname || stringVariable || Returns all of the items in "arrayname" as a string separated by semicolons (;)<br />
|-<br />
| array || fromstring || arrayname || delimiter;string || Creates an array from "string", splitting "string" on "delimiter" to separate the items<br />
|-<br />
| array || statusmarkers|| arrayname;tokenid || none|| Creates an array (arrayname) of the active statusmarkers (sometimes called Token Markers) for the specified tokenid<br />
|-<br />
| math || angle || math;angle;tokenid;tokenid|| rollVariable || Calculates the angle between two tokens and returns the value in degrees<br />
|-<br />
| math || ceil || math;ceil;value || rollVariable || Rounds '''value''' up to the next integer, dropping any decimal portion of the number<br />
|-<br />
| math || clamp || math;clamp;value;lowerBound;upperBound || rollVariable || Returns '''value''', but restricted to the range of '''lowerBound''' and '''upperBound'''.<br />
|-<br />
| math || floor || math;floor;value || rollVariable || Rounds '''value''' down, dropping any decimal portion of the number<br />
|-<br />
| math || max || math;max;valueA;valueB || rollVariable || Returns the larger of '''valueA''' vs '''valueB'''<br />
|-<br />
| math || min || math;min;valueA;valueB || rollVariable || Returns the smaller of '''valueA''' vs '''valueB'''<br />
|-<br />
| math || round || math;round;value || rollVariable || Rounds '''value''' to the nearest integer<br />
|-<br />
| string || length || string;length;stringValue || rollVariable || Returns the length of '''stringValue''' in characters<br />
|-<br />
| string || before || string;before;searchText;stringValue || stringVariable || Searches '''stringValue''' for '''searchText''' and returns the portion of '''stringValue''' prior to that text<br />
|-<br />
| string || after || string;after;searchText;stringValue || stringVariable || Searches '''stringValue''' for '''searchText''' and returns the portion of '''stringValue''' after that text<br />
|-<br />
| string || left || string;left;count;stringValue || stringVariable || Returns the leftmost '''count''' characters of '''stringValue'''<br />
|-<br />
| string || right || string;right;count;stringValue || stringVariable || Returns the rightmost '''count''' characters of '''stringValue'''<br />
|-<br />
| string || replace || string;replace;searchText;replaceText;stringValue || stringVariable || Replaces '''searchText''' in '''stringValue''' with '''replaceText''' and returns the resulting string<br />
|-<br />
| string || replaceall || string;replace;searchText;replaceText;stringValue || stringVariable || Replaces all intances of '''searchText''' in '''stringValue''' with '''replaceText''' and returns the resulting string '''''Requires 1.2.9+'''''<br />
|-<br />
| string || trim || string;trim;stringValue || stringVariable || Removes leading and trailing spaces from stringValue and returns the result. <br />
|-<br />
| string || substring || string;substring;start;count;stringValue || stringVariable || Returns '''count''' characters starting at '''start''' from '''stringValue'''<br />
|-<br />
| 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.<br />
|-<br />
| string || tolowercase || string;tolowercase;stringValue || stringVariable || Converts the passed string to lower case and assigns to the passed variable name. <br />
|-<br />
| string || touppercase || string || stringVariable || Converts the passed string to upper case and assigns to the passed variable name. <br />
|-<br />
| 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. <br />
|-<br />
| 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.<br />
|-<br />
| 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'''.<br />
|-<br />
| turnorder || clear || none || none || Clears all entries from the {{Turn Tracker}}/Initiative<br />
|-<br />
| turnorder || addtoken || tokenid;trackervalue || none || Adds the token represented by "tokenid" to the initiative tracker with an initiavie value of "trackervalue"<br />
|-<br />
| turnorder || replacetoken || tokenid;trackervalue || none || Replaces the token represented by "tokenid" in the initiative tracker with an initiavie value of "trackervalue". Will add the token if it doesn't exist in the tracker.<br />
|-<br />
| turnorder || removetoken || tokenid || none || Removes the token represented by "tokenid" from the initiative tracker if it exists<br />
|-<br />
| turnorder || addcustom || textlabel;trackervalue || none || Add a custom text entry to the {{Turn Tracker}}/Initiative named "textlabel" with an initiative value of "trackervalue"<br />
|-<br />
| system || date || getdatetime || stringVariable || Returns the date time in the active timezone (see settings) <br />
|-<br />
| system || date || getdate || stringVariable || Returns the date in the active timezone (see settings) <br />
|-<br />
| system || date || gettime || stringVariable || Returns the time in the active timezone (see settings)<br />
|-<br />
| system || dumpvariables || "rolls", "string", or "array" || none || Dumps all of the defined variables of the indicated type to the console log<br />
|-<br />
| system || findability || system;findability;charactername;abilityname || stringVariable || Returns the object ID of the ability on the indicated character or "AbilityNotFound"<br />
|-<br />
|}<br />
<br />
Examples:<br />
<br />
<pre><br />
--~HowFarAway|distance;@{selected|token_id};@{target|token_id}<br />
</pre><br />
<br />
Returns the distance (Chebyshev) between the selected and target tokens and stores it in "HowFarAway".<br />
<br />
<pre><br />
--SelectedDudes|getselected<br />
</pre><br />
<br />
If 5 tokens were selected, 6 variables would be created: SelectedDudesCount (with a value of 5), SelectedDudes1, SelectedDudes2, SelectedDudes3, SelectedDudes4, SelectedDudes5.<br />
<br />
=== Information Request (--i) ===<br />
<br />
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.<br />
<br />
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.<br />
<br />
After the user has clicked the button and responded to the requests, ScriptCards will resume processing the script from where it left off.<br />
<br />
Here is an example “i” line:<br />
<br />
<pre><br />
--IScriptCards needs additional information to continue;Click to select a target and provide information|t;MyNewTarget;Missile1Target||q;MyNameIs;What is your name?<br />
</pre><br />
<br />
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.<br />
<br />
Supported information request types are “t” for target token, and “q” for query.<br />
<br />
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).<br />
<br />
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:<br />
<br />
<pre><br />
q;UserName;What is your name?|Fred|Bob|Sally|Nancy<br />
</pre><br />
<br />
Would have a dropdown menu with four choices.<br />
<br />
=== Object Modification (--!) ===<br />
<br />
'''''Requires ScriptCards version 1.5.0+'''''<br />
<br />
Object modification support is now available in ScriptCards. As of 1.5.0, you can use the --! command to modify object properties in the game. This may help reduce the reliance on the --@ command to run other API commands to modify token/character values. The biggest benefit of this is that the changes happen as the script is processing, so the new values are available right away. <br />
<br />
The format of the command is:<br />
<pre><br />
--!<objectType>:<objectId>|setting:value|setting:value|setting:value...<br />
</pre><br />
<br />
'''objectType''' can be one of "t" for token, "c" for character, or "a" for character attribute<br />
<br />
'''objectId''' can be a token id or a character id (or "S"/"T" for the Source/Target token/char defined with --#sourcetoken and --#targettoken)<br />
<br />
'''setting''' and '''value''' pairs can be chained in a single statement separated by | to impact more than one property/attribute with a single line<br />
<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
Examples:<br />
<br />
Set the value of bar1_value for the selected token to 5:<br />
<pre> --!t:@{selected|token_id}|bar1_value:5</pre><br />
Add 1 to the bar3_value for the selected token:<br />
<br />
<pre> --!t:@{selected|token_id}|bar3_value:+=1</pre><br />
Set bar2_value to 5 and bar2_max to 10 for the selected token<br />
<br />
<pre> --!t:@{selected|token_id}|bar2_value:5|bar2_max:10</pre><br />
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:<br />
<br />
<pre> --!a:@{selected|token_id}|dndstyling:on|size:enormous|!attitude:epic</pre><br />
Adds 50 to the npc_xp attribute for the character represented by the selected token, displaying the value before and after the update:<br />
<br />
<pre><br />
!script {{<br />
--+XP|[*@{selected|token_id}:npc_xp]<br />
--!a:@{selected|token_id}|npc_xp:+=50<br />
--+XP|[*@{selected|token_id}:npc_xp]<br />
}}<br />
</pre><br />
<br />
Note that asynchronous read/update fields (bio, notes, gmnotes) are not currently supported.<br />
<br />
== Inline Formatting ==<br />
<br />
Inline formatting is processed on Direct Output lines only (--+ lines) and the following inline format markup is available:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Formatting Tags !! Description<br />
|-<br />
| [b]..[/b] || Bold the text between the markers <br />
|-<br />
| [i]..[/i] || Italicize the text between the markers <br />
|-<br />
| [u]..[/u] || Underline the text between the markers <br />
|-<br />
| [s]..[/s] || Strike-Thru the text between the markers <br />
|-<br />
| [c]..[/c] || Center alignment <br />
|-<br />
| [l]..[/l] || Left alignment <br />
|-<br />
| [r]..[/r] || Right alignment <br />
|-<br />
| [j]..[/j] || Full justification alignment <br />
|-<br />
| [#xxx]..[/#] or [#xxxxxx]..[/#] || Use a 3 or 6 digit hex code to colorize the text between the markers <br />
|-<br />
| [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, <code>[img width=128 height=128]</code> )<br />
|-<br />
| [button]caption::action[/button] || Create a button with the label "caption" that performs the action defined by "action". By default, buttons will be colored according the the buttontextcolor and buttonbackground card settings. You can optionally color individual buttons by specifying a text color and a background color as part of the [button] command (ie, [button:#ffffff:#000000] will create a button with white text on a black background. In order to set a background color, the foreground color must be specified.<br />
|-<br />
| [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. By default, buttons will be colored according the the buttontextcolor and buttonbackground card settings. You can optionally color individual buttons by specifying a text color and a background color as part of the [sheetbutton] command (ie, [sheetbutton:#ffffff:#000000] will create a button with white text on a black background. In order to set a background color, the foreground color must be specified.<br />
|-<br />
| [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. By default, buttons will be colored according the the buttontextcolor and buttonbackground card settings. You can optionally color individual buttons by specifying a text color and a background color as part of the [rbutton] command (ie, [rbutton:#ffffff:#000000] will create a button with white text on a black background. In order to set a background color, the foreground color must be specified.<br />
|-<br />
| [t] || Converted to HTML table tag. Text after the "t" will be included inside the tag (width, border, etc)<br />
|-<br />
| [/t] || Converted to HTML close table tag.<br />
|-<br />
| [tr] || Converted to HTML table row tag. Text after the "tr" will be included inside the tag<br />
|-<br />
| [/tr] || Converted to HTML close table row tag.<br />
|-<br />
| [td] || Converted to HTML table cell tag. Text after the "tr" will be included inside the tag<br />
|-<br />
| [/td] || Converted to HTML close table cell tag.<br />
|}<br />
<br />
Code Example<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Formatting Tags !! Description<br />
|-<br />
| <pre>!script {{<br />
--#title|Inline Formatting Examples<br />
--+|This text [b]is bolded[/b]<br />
--+|This text [i]is italicized[/i]<br />
--+|This text [u]is underlined[/u]<br />
--+Alignment|[l]Left[/l]<br />
--+|[c]Center[/c]<br />
--+|[r]Right[/r]<br />
--+|[j]This long bit of text is justified to fit smoothly into the display area for the card with justified wrapping.[/j]<br />
--+Colorized|[#f00]Red[/#] [#0f0]Green[/#] [#00f]Blue[/#]<br />
--+Button|[button]Do Something::DoOnClick[/button]<br />
--+Button Colors|[button:#000:#f00]Red::RedClick[/button] [button:#000:#0f0]Blue::BlueClick[/button] [button:#000:#00f]Blue::BlueClick[/button]<br />
--+Table:|<br />
--+|[t border=2 width=100%][tr][td]Cell1[/td][td]Cell2[/td][/tr][tr][td]Cell3[/td][td]Cell4[/td][/tr][/t]<br />
}}</pre> || [[File:Sc-formatting_example.png]]<br />
|}<br />
<br />
== Variables ==<br />
<br />
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. While it is possible to assign both a string and a roll variable the same name, doing so will likely result in confusion when looking at the script later, so it is not recommended.<br />
<br />
String Variables are assigned with the --& statement and are referenced using [&variableName] notation.<br />
<br />
Roll Variables are assigned with the --= statement, and the assignment value is always processed by the ScriptCards Roll Processor (resolves dice rolls, etc.)<br />
<br />
There are a handful of variables assigned automatically when a ScriptCard is executed. These are all string variables, and are:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Variable !! Value<br />
|-<br />
| SendingPlayerID || Contains the object ID of the player that sent the macro<br />
|-<br />
| SendingPlayerName || Contains the display name of the player<br />
|-<br />
| SendingPlayerColor || Contains the color code associated with the player<br />
|-<br />
| SendingPlayerSpeakingAs || The contents of the "Speaking As" dropdown window<br />
|-<br />
| SendingPlayerIsGM || Contains 1 if the player is a GM, and 0 if the player is NOT a GM<br />
|}<br />
<br />
== Arrays ==<br />
<br />
Arrays are a special type of variable, and are managed by the function (<nowiki>--~</nowiki> command). All of the array function commands follow the same pattern:<br />
<br />
<pre>--~variableName|array;subcommand;arrayname;param1;param2;param3;...</pre><br />
<br />
Not all array commands return anything to "variableName". The function table above will specify the return type of the command if any.<br />
<br />
There are a couple of different ways to create an array:<br />
<br />
The '''define''' array subcommand creates (or recreates) an array and assigns it values - one for each included parameter after the array name. For example:<br />
<br />
<pre>--~|array;define;Fruits;mango;peach;strawberry;apricot;banana;apple</pre><br />
<br />
will create an array called '''Fruits''' with 6 elements in the order listed in the command (mango, peach, etc.)<br />
<br />
You can also use two other subcommands to create arrays based on tokens:<br />
<br />
<pre>--~Count|array;pagetokens;Everybondy;@{selected|token_id}</pre><br />
<br />
and<br />
<br />
<pre>--~Count|array;selectedtokens;Selected</pre><br />
<br />
In both cases, arrays of tokens will be created, and a string variable called "Count" will be set to the number of tokens in the array. The '''pagetokens''' command returns (by default) all of the tokens on the page that contains the token passed as the parameter after the array name. You can filter the tokens that "pagetokens" includes in the array by appending an optional parameter describing the type of token you are looking for:<br />
<br />
<pre>--~Count|array;pagetokens;Everybondy;@{selected|token_id};npc</pre><br />
<br />
Will return only tokens on the page that represent characters that do not have a ''controlledby'' parameter set. The available options are "all" (default), "char", "graphic", "pc", and "npc".<br />
<br />
The '''selectedtokens''' command returns an array with all of the tokens that were selected when the script was called.<br />
<br />
You can also use an arbitrary string to create an array, specifying a delimiter with the '''fromstring''' command:<br />
<br />
<pre><br />
--&names|Fred<br />
--&names|+,Sally<br />
--&names|+,Ted<br />
--&names|+,Joyce<br />
--~|array;fromstring;,;[&names]<br />
</pre><br />
<br />
The above example builds a comma-separated string and then uses "fromstring" to create an array with 4 elements from it, specifying the comma as the delimiter.<br />
<br />
Finally, you can use the '''statusmarkers''' command to create an array with one entry for each active status marker on a specified token:<br />
<br />
<pre>--~|array;statusmarkers;Conditions;@{selected|token_id}</pre><br />
<br />
will create an array with one entry for each status active on the selected token. The array elements will be the internal name of the status (if you are using custom status marker packs, the names will be specified in the marker pack).<br />
<br />
'''Traversing Arrays'''<br />
<br />
Each array keeps track of an internal index position (starting at 0). Several commands let you manage this index:<br />
<br />
*'''getindex''' returns the current index value<br />
*'''setindex''' sets the index to the specified location in the array<br />
*'''getlength''' returns the number of elements in the array<br />
*'''indexof''' returns the index location of the specified element<br />
<br />
Other commands let you retrieve values from the array:<br />
<br />
*'''getfirst''' sets the index to 0 and returns the value at that position<br />
*'''getnext''' advances the index by 1 and returns the new current value<br />
*'''getprevious''' reduces the index by 1 and returns the new current value<br />
*'''getlast''' sets the index to the last elements in the array and returns the new current value<br />
<br />
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.<br />
<br />
'''Manipulating Array Elements'''<br />
<br />
Several array commands deal with inserting, removing, and modifying elements:<br />
<br />
*'''add''' works just like define, except that it takes an existing array and adds elements to it based on the passed parameters<br />
*'''remove''' looks for items matching each passed parameter and removes them from the indicated array if they exist<br />
*'''removeat''' allows you to specify an index location in the array and remove the element at that position<br />
*'''replace''' searches an array for a value and replaces all occurrences of it with a new value (if found)<br />
*'''sort''' sorts the elements in the array in ascending order<br />
*'''strinfigy''' returns a string variable that includes each array element separated by semicolons (;) <br />
<br />
'''Referencing Array Elements'''<br />
<br />
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.<br />
<br />
<pre><br />
!script {{<br />
--~dummy|array;pagetokens;myarray;@{selected|token_id}<br />
--~count|array;getcount;myarray<br />
--+Total:|There are [&count] graphical objects on the page<br />
--~testvar|array;getfirst;myarray<br />
--:loop|<br />
--+Value|[*[&testvar]:character_name]<br />
--~testvar|array;getnext;myarray<br />
--?[&testvar] -ne ArrayError|loop<br />
--+Loop1|Is Done!<br />
}}<br />
</pre><br />
<br />
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:<br />
<br />
<pre><br />
!script {{<br />
--~dummy|array;pagetokens;myarray;@{selected|token_id}<br />
--~count|array;getcount;myarray<br />
--+Total:|There are [&count] graphical objects on the page<br />
--%loopCounter|1;[&count]<br />
--+Value|[*[@myarray([&loopCounter])]:character_name]<br />
--%|<br />
--+Loop|Is Done!<br />
}}<br />
</pre><br />
<br />
This line : <nowiki>--+Value|[*[@myarray([&loopCounter])]:character_name]</nowiki> uses [@arrayName(index)] format (inside a [*characterid:attribute] syntax) to perform the same task as running through the loop with the index.<br />
<br />
(Note: Additional examples are on the way...)<br />
<br />
== For...Next Loops ==<br />
<br />
For...Next loops in ScriptCards are supported with the with the --% statement type. A loop is defined by starting off with:<br />
<br />
<pre><br />
--%LoopCounter|<start>;<end>;[step]<br />
</pre><br />
<br />
The start and end values are required, while the step parameter is optional. If the step is omitted, it will be assumed to be 1. A string variable named after the line tag ("LoopCounter" in the case above) will be created and will hold the current iteration value for the loop. Here is a real example:<br />
<br />
<pre><br />
--%LoopCounter|1;10;1<br />
</pre><br />
<br />
This will begin a loop identified by "LoopCounter" that will start at 1, increasing by 1 each iteration (the step) until it has completed 10 executions.<br />
<br />
The "next" statement is simply <code>--%|</code>, with no tag or parameters. This indicates to ScriptCards that it should increment the counter and go back to the beginning of the loop. Extending the example above:<br />
<br />
<pre><br />
!script {{<br />
--%LoopCounter|1;10;1<br />
--=Roll|1d20<br />
--+Loop|Counter is [&LoopCounter], roll was [$Roll]<br />
--%|<br />
}}<br />
</pre><br />
<br />
The <code>--%!|</code> sequence will break out of the loop, no matter how many iterations are remaining.<br />
<br />
The % and %! character sequences can also be used as part of a 1.2.1+ non-branching conditional to continue or break the loop:<br />
<br />
<pre><br />
--?"X[&RollInto]X" -eq "XX"|%<br />
</pre><br />
<br />
In this example, if the string variable RollInfo is empty, the loop will return to the top and continue with the next iteration, while:<br />
<br />
<pre><br />
--?"X[&RollInto]X" -eq "XX"|%!<br />
</pre><br />
<br />
Would cause the whole loop to end if the condition were true.<br />
<br />
== Referencing ==<br />
<br />
=== Roll Variables===<br />
<br />
Roll Variables can be referenced from the content portion of any line type, and from the tag portion of conditional statements. The referenced value is replaced when the line is executed.<br />
<br />
There are several modifiers that can be used to reference parts of a roll:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Modifier !! Meaning<br />
|-<br />
| No modifier || In a Direct Output Line (<nowiki>--+</nowiki>), GM Output Line (<nowiki>--*</nowiki>), or String Assignement (<nowiki>--&</nowiki>), 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<br />
|-<br />
| .Total || The end result of the roll equation. Formatting rules for "No Modifier" apply based on line type. <br />
|-<br />
| .Raw || The total value of the roll variable without any formatting, no matter what kind of line the reference is used in.<br />
|-<br />
| .Base || The cumulative result of any dice rolled in the Roll Text (Numeric modifiers are not included) <br />
|-<br />
| .Ones || The number of dice in the roll that came up as 1s <br />
|-<br />
| .Aces || The number of dice in the roll that came up as the maximum number on the die <br />
|-<br />
| .Odds || The number of dice in the roll that came up with an odd number <br />
|-<br />
| .Evens || The number of dice in the roll that came up with an even number <br />
|-<br />
| .RollText || The raw text of the roll that was use to generate the results <br />
|-<br />
| .Text || A text representation of the results of the roll, including the numbers rolled for each die <br />
|-<br />
| .tableEntryText || The text portion of the result of a table roll<br />
|-<br />
| .tableEntryImgURL || The image source portion of the result of a table roll<br />
|-<br />
| .tableEntryValue || If the tableEntryText is purely numeric, will contain the numeric value<br />
|}<br />
<br />
=== String Variables ===<br />
<br />
To reference a string variable, use the notation [&variablename]. String variables can be referenced in direct output, roll variable assignment, and string variable assignment statements.<br />
<br />
=== Character/Token Attributes ===<br />
<br />
A character or token attribute can be referenced from content portion of any type of line and is substituted when the line is executed. The general format for referencing a character attribute is [*ID:attribute]. ID can be a token ID or a character ID (these start with a dash). Additionally if you have specified a sourceToken or targetToken, you can substitute "S" or "T" for the ID (for example [*S:npc_type] will retrieve the npc_type attribute from the source token.<br />
<br />
By default, all attribute references will be pulled from the '''''character''''' object that the ID represents (either directly or by being a Token ID that represents a character).<br />
<br />
Keep in mind, that if you want to access the "max" of a character attribute (for example, the max hit points), then you cannot trust the name that your roll20 character sheet shows you when you hover your mouse over the max hit points. For example, this reference will not work: [*S:hp_max]. Instead, you need to use this reference: [*S:hp^].<br />
<br />
If your ID refers to a token, token attributes can be accessed by preceding the attribute name with "t-", for example [*S:t-aura1_radius]. Supported token attributes are:<br />
'''(NOTE: As of version 1.6.1 of ScriptCards, the below list is no longer a limitation on the token attributes you can reference. All token attributes available in Roll20 can now be accessed and the need to update the internal list as new attributes are added has been eliminated.)'''<br />
<br />
{|<br />
| t-name || t-id || t-statusmarkers || t-bar1_value<br />
|-<br />
| t-bar1_max || t-bar2_value || t-bar2_max || t-bar3_value<br />
|-<br />
| t-bar3_max || t-top || t-left || t-width<br />
|-<br />
| t-height || t-rotation || t-layer || t-aura1_radius<br />
|-<br />
| t-aura1_color || t-aura2_radius || t-aura2_color || t-aura1_square<br />
|-<br />
| t-aura2_square || t-tint_color || t-light_radius || t-light_dimradius<br />
|-<br />
| t-light_angle || t-light_losangle || t-light_multiplier || t-light_otherplayers<br />
|-<br />
| t-light_hassight || t-flipv || t-fliph || t-controlledby<br />
|-<br />
| t-_cardid || t-_pageid || t-imgsrc || t-bar1_link<br />
|-<br />
| t-bar2_link || t-bar3_link || t-represents || t-layer<br />
|-<br />
| t-isdrawing || t-name || t-gmnotes || t-showname<br />
|-<br />
| t-showplayers_name || t-showplayers_bar1 || t-showplayers_bar2 || t-showplayers_bar3<br />
|-<br />
| t-showplayers_aura1 || t-showplayers_aura2 || t-playersedit_name || t-playersedit_bar1<br />
|-<br />
| t-playersedit_bar2 || t-playersedit_bar3 || t-playersedit_aura1 || t-playersedit_aura2<br />
|-<br />
| t-lastmove || t-adv_fow_view_distance || t-has_bright_light_vision || t-has_night_vision<br />
|-<br />
| t-night_vision_distance || t-emits_bright_light || t-bright_light_distance || t-emits_low_light<br />
|-<br />
| t-low_light_distance || t-has_limit_field_of_vision || t-limit_field_of_vision_center || t-limit_field_of_vision_total<br />
|-<br />
| t-has_limit_field_of_night_vision || t-limit_field_of_night_vision_center || t-limit_field_of_night_vision_total || t-has_directional_bright_light<br />
|-<br />
| t-directional_bright_light_center || t-directional_bright_light_total || t-has_directional_dim_light || t-directional_dim_light_center<br />
|-<br />
| t-directional_dim_light_total || t-lightColor || t-tooltip || |<br />
|}<br />
<br />
'''''It is important to note that some attributes names on tokens have corresponding attribute names on characters, which represent different values. For example, [*T:id] returns the character ID, while [*T:t-id] returns the token ID.'''''<br />
<br />
=== Subroutine Parameters ===<br />
<br />
When using a gosub statement (-->) or a conditional marked as a gosub (prefixing the label with a > character), you can pass any number of parameters separated by semicolons (;) that the code in the subroutine can utilize.<br />
<br />
Subroutine parameters are numbered starting at 1, and are accessed by using the notation [%number%], so the first parameter is [%1%], the second is [%2%], etc.<br />
<br />
Parameter substitution happens on all line types, and happens prior to character attribute references or roll variable substitution.<br />
<br />
=== Campaign Attribute ===<br />
You can retrieve properties of the API's Campaign object with the [*C:attributename] syntax. For example, [*C:playerpageid] will retrieve the current player ribbon page from the Campaign object.<br />
<br />
=== Page Attributes ===<br />
If you have set the '''activepage''' parameter, you can retrieve page-related properties with the [*P:attributename] syntax, including the page's UDL parameters.<br />
<br />
=== Repeating Section Values ===<br />
<br />
You can reference repeating attribute data using the syntax [*R:attributename] syntax (similar to referencing standard character attributes). The currently active repeating row information will be used to retrieve attribute values. You can also retrieve the full attribute name for a repeating row attribute by using the [*R>attributename] notation. This is useful to pass to things like chatsetattr.<br />
<br />
See the section named [[#Repeating Section Access (--R)|Repeating Section Access]] for more information.<br />
<br />
=== Array Elements ===<br />
After an array has been declared, the elements can be referenced with [@arrayName(index)]. Array indices start at 0.<br />
<br />
=== ScriptCards Settings ===<br />
As of version 1.6.0, it is now possible to reference ScriptCards settings (set with the --# command) using the [#settingname] syntax (ie, [#title] will be replaced with the title setting at the time the reference is interpreted.<br />
<br />
== Deferred Resolution for Meta Scripts ==<br />
<br />
As of 1.2.9, ScriptCards supports a deferral character for use when calling another API script with via the <code>--@</code> statement, to defer processing of meta script references so they get processed prior to the sub-API call instead of prior to ScriptCards execution. To defer this processing for meta script ([[Tim#SelectManager|SelectManager]], [[Tim#Fetch|Fetch]]) by inserting a deferral character into the meta call. For example, if I want to have ScriptCards call [[TokenMod]] as if the token for "Quej Gr'stra" (yes, I let Roll20 name my test NPCs) I could use something like this:<br />
<br />
<pre> --@token-mod|{^& select Quej Gr'stra} _on showname</pre><br />
<br />
The <code>^</code> in between <code>{</code> and <code>&</code> will prevent SelectManager from seeing the call when the ScriptCard script is processed, but the <code>--@</code> statement will remove the deferral character so the command that will be sent by ScriptCards is:<br />
<br />
<pre>!token-mod {& select Quej Gr'stra} --on showname</pre><br />
<br />
With the deferral character removed, SelectManager will see the <code>{& select ...}</code> and do its magic.<br />
<br />
While the default deferral character is <code>^</code>, the deferral character is a setting that can be changed:<br />
<br />
<pre> --#deferralcharacter|%</pre><br />
<br />
Will make <code>%</code> the deferral character for future <code>--@</code> statements in the running script.<br />
<br />
Supported [[API:Meta_Scripts|Meta Script]] structures:<br />
* <code>{^&...}</code> - for [[Tim#SelectManager|SelectManager]]<br />
* <code>@^(...)</code> and <code>*^(...)</code> for [[Tim#Fetch|Fetch]]<br />
* <code>get^.</code> and <code>set^.</code> for [[Tim#Fetch|Muler]] (''''' v 1.4.5+ ''''')<br />
<br />
== Arrays ==<br />
<br />
Arrays are a new data type introduced in version 1.1.12 of ScriptCards, and are manipulated with associated function (--~) commands.<br />
<br />
* Arrays are a lists of strings. Items in an array cannot contain the semi-colon (;) character, as that is used to separate parameters in the function code that deals with arrays.<br />
* Arrays are accessed via the --~ script command. In some cases, the value of the tag (variable name) for array commands is not used, and can be a dummy value or simply omitted. I have omitted them in the statements below.<br />
* All commands that DO return a value return string values, even if the content is numeric.<br />
* If a command returns a value and there is some sort of reason that it isn't an array value, you will get "ArrayError" in the return value. This can happen if you reach the end of an array while stepping through it, for example, so checking for "ArrayError" can serve as the end condition for a loop.<br />
* Each array keeps track of its current index, allowing you to step forward and backwards through arrays.<br />
* Any number of arrays can be defined.<br />
* Unlike string variables and roll variables, array variables cannot (currently) be referenced directly. It is necessary to use the function (--~) syntax to manipulate arrays and get values from them as strings for use in other parts of your script.<br />
<br />
== Reentrant Scripts ==<br />
<br />
Reentrant scripts allow you to create buttons in your script code that will re-execute the script at a given label within the code. If you set the reentrant setting (<code>--#reentrant|somevalue</code>) to a non-zero value, your setting and variable information will be preserved between executions. Reentrant script can be used to present menus or choices and then continue acting.<br />
<br />
'''''Important''''': The value of the reentrant setting will be used to identify the appropriate script to resume when reentrancy is used. If more than one character can potentially run the same script at the same time, it is a good practice to include the character ID in the reentrant setting in order to maintain a separate list of variables. Something like:<br />
<br />
<pre><br />
--#reentrant|My Cool Script @{selected|character_id}<br />
</pre><br />
<br />
Reentrant buttons are created with the <code>[rbutton]Caption::ReentryLabel;Parameter[/rbutton]</code> construct. The caption will be displayed on the generated button. <code>ReentryLabel</code> is the name of a label in your script that the button will jump to when clicked, and Parameter will be passed in as a string value called <code>reentryval</code>.<br />
<br />
Example:<br />
<pre><br />
!script {{<br />
--#reentrant|testing<br />
--=Roll|1d20<br />
--+Roll|[$Roll]<br />
--&String|That was a [$Roll.Raw]!<br />
--~x|array;define;MyArray;Apple;Banana;Orange<br />
--+Try it|[rbutton]Hello!::EXEC_PC_SPELL;9[/rbutton]<br />
--X|<br />
<br />
--:EXEC_PC_SPELL|<br />
--+ReentryVal|[&reentryval]<br />
--+The value of Roll is|[$Roll]<br />
--+Value of String|[&String]<br />
--+Array|[@MyArray(0)]<br />
--X|<br />
}}<br />
</pre><br />
<br />
This script sets up some variables and then displays a button labeled "Hello!". If the user clicks the button, the script will be re-entered starting at <code>EXEC_PC_SPELL</code>, which will display the content of the variables from the original execution.<br />
<br />
'''''Note: This section needs to be expanded upon'''''<br />
<br />
==Libraries ==<br />
=== Procedure Libraries ===<br />
<br />
You can now create [[handouts]] in your game in Roll 20 with the name format "ScriptCards Library NAME", where name is a name you assign to the library. Library names are case sensitive. It is my hope that the more proficient ScriptCards scripters out there will provide procedure libraries (or procedures that can be included in libraries) for others to use to make their scripting life easier. Be they specific to a game system, or to a type of activity, I think a robust set of libraries that GMs could use to enhance their scripting capabilities would be very valuable to the community. Should such things begin to emerge, I’ll create a portion of the ScriptCards Wiki page to house them.<br />
<br />
To include one or more libraries in a script, use the +++libname+++ directive (does not need a -- line associated with it). Multiple library names can be specified by separating them with semicolons (i.e., +++General;dnd5elib;Colorize+++ would include three libraries (General, dnd5elib, and Colorize).<br />
<br />
Included libraries are separated from the main script code by the automatic inclusion of "--X|" before the first library is appended to the script, and all libraries are loaded at the end of the script before script processing takes place.<br />
<br />
Procedures and labels in libraries can be used just as if they were included in the body of your script. Note that this DOES mean that you could, technically, jump into a library with a direct branch (--^) or direct branch conditional, but I recommend using libraries to store reusable procedures.<br />
The Notes section of the library handout stores the library code, and is written just like any other ScriptCards code except:<br />
<br />
* They cannot use roll queries (?{Some Prompt:}) to get information from the user at execution time.<br />
* They cannot use @{} notation to access character and token information.<br />
<br />
Both of these limitation stem from the fact that Procedure Libraries are not processed by the chat server, which is what handles these items.<br />
<br />
Here is an example of handling damage modifications (resistance, vulnerability, and immunity) in D&D 5E with a library:<br />
<br />
<pre><br />
!script {{<br />
+++dnd5elib+++<br />
--#|Damage Modifiers Test<br />
--#targettoken|@{target|token_id}<br />
-->Lib5E_CheckDamageModifiers|ResistType;fire<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] fire damage<br />
<br />
-->Lib5E_CheckDamageModifiers|ResistType;cold<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] cold damage<br />
<br />
-->Lib5E_CheckDamageModifiers|ResistType;poison<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] poison damage<br />
<br />
-->Lib5E_CheckDamageModifiers|ResistType;acid<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] acid damage<br />
<br />
--X|<br />
}}<br />
</pre><br />
<br />
Library content (In a handout called “ScriptCards Library dnd5elib” NOTE: Paste into Notepad first and then paste into the handout in Roll20 to avoid bringing over HTML formatting from the web site):<br />
<br />
<pre><br />
--/|ScriptCards Library: dnd5elib version 0.0.1<br />
--/|Provides various utility procedures for D&D 5E games<br />
<br />
--/|Lib5E_CheckDamageModifiers handle damage resistance, vulnerability, and immunity. <br />
--/|Pass a string variable to be filled with a string to be appended to a dice roll and the damage type <br />
<br />
--:Lib5E_CheckDamageModifiers|damageVariableName;damageType<br />
--&[%1%]|<br />
--?"[*T:npc_vulnerabilities]" -inc "[%2%]"|>_Lib5E_IsVulnerable;[%1%]<br />
--?"[*T:npc_resistances]" -inc "[%2%]"|>_Lib5E_IsResistant;[%1%]<br />
--?"[*T:npc_immunities]" -inc "[%2%]"|>_Lib5E_IsImmune;[%1%]<br />
--<|<br />
<br />
--:_Lib5E_IsVulnerable| --&[%1%]| * 2 [Vulnerable] --<|<br />
--:_Lib5E_IsResistant| --&[%1%]| \ 2 [Resistant] --<|<br />
--:_Lib5E_IsImmune| --&[%1%]| * 0 [Immune] --<|<br />
</pre><br />
<br />
The idea is that the functions in the library create a string that can be appended to a roll to modify the output based on resistances, so you pass Lib5E_CheckDamageModifiers the name of the string variable you want to use and the damage type. The variable (ResistType in this case) will include either nothing, “* 2 [Vulnerable]”, “\ 2 [Resistant]”, or “* 0 [Immune]” which can be included in a roll assignment (--=) to modify the damage as appropriate. The order here might be important if an NPC is misconfigured to be both resistant and immune to the same damage type. Since immune is an absolute, having it last ensures that it will override resistant or vulnerable. A creature that is both vulnerable and resistant (again, misconfigured) will come back as resistant since that condition is checked after vulnerable.<br />
Some notes: I prefix my library labels with either “Lib5E_” or “_Lib5E_” as a clarity convention. This isn’t strictly necessary but you should be aware that if two libraries (or if your script and a library) define the same label, the last label defined will win. Since libraries are appended to the end of the script in the order you include them in the +++libname+++ directive, you can somewhat control this, but it is probably best to avoid re-declaring labels. <br />
<br />
In my case, items beginning with “Lib5E_” are intended to be called by scripts, while items beginning with “_Lib5E_” are intended to be used as subroutines by the “public” procedures. Of course, there is no reason you couldn’t call them directly.<br />
<br />
You might also note that I’ve included some library information in comment lines (--/|) at the top of the library. These are ignored by ScriptCards, and are a good way to convey requirements, parameters, usage information, etc.<br />
<br />
=== Example Libraries ===<br />
<br />
==== dnd5elib ====<br />
<br />
[https://github.com/kjaegers/ScriptCards Download the dnd5elib Library from the ScriptCards GitHub]<br />
<br />
The '''dnd5elib''' library provides a collection of utility procedures that help simplify dealing with the D&D 5E Official Sheet. Some of the procedures in this library require '''chatsetattr''' to be installed in your game. This is a growing library, and currently only has a handful of routines. They are:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Procedure Name !! Notes<br />
|-<br />
| style="white-space:nowrap" | Lib5E_CheckDamageModifiers || This procedure can be used to evaluate vulnerabilities, resistances, and invulnerabilities on an NPC. After setting the --#target| parameters, pass the Lib5E_CheckDamageModifiers procedure a variable name (no reference information) and a damage type (i.e., fire, cold, bludgeoning, etc.), and the procedure will then create a string variable with with a name equal to the first parameter that you passed into the procedure. This variable will contain a string that can be included in a roll line (--=), in order to modify the roll as appropriate. For example, '''-->Lib5E_CheckDamageModifiers|ResistType;fire''' will check the current target character's attributes for "fire" and will either return an empty string (no references), "* 0 [Immune]" if the creature is immune, "\ 2 [Resistant]" if the creature is resistant, or "* 2 [Vulnerable]" if the creature is vulnerable to fire damage.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_DeductSpellSlot || Pass in a character_id and a slot level, and the script will expend one spell slot of that level, capping the value at 0 slots remaining. For Example '''<nowiki>-->Lib5E_DeductSpellSlot|@{selected|character_id};1</nowiki>''' to deduct a first level spell slot from the selected character.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_FindResource || Used to locate a resource value on a character. Pass in a character_id, a resource name, and two variable names. The procedure will check both repeating and non-repeating resources looking for a resource whose name matches what was passed in and return three variables. The first will be a string variable named for the 3rd parameter and contains the attribute name of the resource's "name" field. The second will be a string variable named after parameter 4 and contains the resource's value field attribute name, and the third variable is a Roll Variable, also named after the 4th parameter that contains the current resource value. Example: '''<nowiki>-->Lib5E_FindResource|@{selected|character_id};Crossbow bolts;ResName;ResValue</nowiki>''' will find "Crossbow bolts" as a resource on the character and return [&ResName] which is the name of the resource attribute, [&ResValue] which is the '''name of the attribute that stores the value''' and [$ResValue] which is the current numeric value of the resource.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Global_Attack_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Attack Modifiers (repeating_tohitmod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Bless" for 1d4 active and "Being Cool" for +2 active, I will get a return string " + 1d4 [Bless] + 2 [Being Cool]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Save_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Save Modifiers (repeating_savemod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Bless" for 1d4 active and "Being Cool" for +2 active, I will get a return string " + 1d4 [Bless] + 2 [Being Cool]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Skill_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Skill Modifiers (repeating_skillmod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Guidance" for 1d4 active and "Being Cool" for +2 active, I will get a return string " + 1d4 [Guidance] + 2 [Being Cool]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_AC_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Save Modifiers (repeating_savemod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Shield of Faith" with a value of 2 active, I will get a return string " + 2 [Shield of Faith]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Damage_Modifiers || Pass a character ID and TWO string variable to set the return value. The first string will be for normal damage, and the second will be the additional damage on a crit. This procedure will look through the Global Damage Modifiers (repeating_damagemod_*) for rows that are active (checked on the character sheet) and return two strings with the dice rolls and descriptions for them (for example, if I have "Sneak Attack" with a value of 1d6 normal and 1d6 critical damage active, I will get a return string " + 1d6 [Sneak Attack]" and another string of " + 1d6 [Sneak Attack CRIT]" that can be used in a dice rolls.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_DivineSmiteDice || Used to calculate the number of dice to be rolled for a paladin's Divine Smite. Pass a target token id, a spell slot level, and a string variable to be set to the dice roll amount based on the NPC_TYPE attribute of the target token. The returned variable will contain a dice roll (like "3d8" that can be used in a --= line)<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Character_Summary || Pass a character ID to outputs a mini character sheet, including clickable buttons for attacks, actions, legendary actions, etc. Will automatically detect a PC vs NPC and output the appropriate sections.<br />
|}<br />
<br />
Due to formatting issues with the Wiki, the library code has been moved to a [https://gist.github.com/kjaegers/52f6049ddd257f0a1288aca4bbde13c5 GITHUB GIT]. Please view the GIST in raw mode and copy the text and paste it into a handout called "ScriptCards Library dnd5elib" in your Roll20 Game.<br />
<br />
== What to Know if you are Coming from PowerCards ==<br />
<br />
''Note: This section is a work in progress.''<br />
<br />
While ScriptCards and PowerCard have very similar output goals, their internals and use are quite different. The table below summarizes some of the major differences between the scripts.<br />
<br />
::{| class="wikitable"<br />
|-<br />
! PowerCards !! ScriptCards <br />
|-<br />
| With a handful of exceptions, all lines in a PowerCard macro are intended to produce a line of output on the final card. || With ScriptCards, ONLY the <code>--+</code> and <code>--*</code> statement types produces output <br />
|-<br />
| PowerCards lines begin with two dashes (<code>--</code>) followed by a unique tag name for the line, followed by a vertical bar and the content for the line. || ScriptCards lines begin with two dashes (<code>--</code>) followed by a '''statement type identifier''', which is a single character that identifies the type of line to the interpreter. This is followed by a tag (frequently optional), a vertical bar, and the parameters for the statement being executed.<br />
|-<br />
| PowerCard macros are always processed top to bottom. Lines can be hidden so they don't output anything, but there is no looping or branching (<code>--SkipTo</code> looks like a branch, but it just hides all of the lines until the referenced label. || ScriptCards scripts support true branching, including direct branching (<code>--^</code>) and procedure branching (<code>--></code>) and (<code>--<</code>). Procedures support parameters and a call stack so procedures can be nested to call other procedures.<br />
|-<br />
| All lines in a PowerCards macro need to have unique tags because PowerCards builds the card as a single JavaScript object using the tag names to store what will be displayed. This is why repeated tag names always result in the last one being shown. || ScriptCards tags do not need to be unique, and in the case of many line types are optional.<br />
|-<br />
| PowerCards conditionals result in either showing or hiding the line they are on. || ScriptCards conditionals '''''only''''' support branching as the result of the comparison. This branching can be direct (a GOTO) or procedural (a GOSUB) '''''NOTE: As of version 1.2.0, ScriptCards also supports roll/string variable assignment as a result of conditional evaluation, and later versions introduced code blocks that can be implemented as a result of a conditional'''''<br />
|-<br />
| PowerCards relies on the Roll20 [[Quantum Roll]] server and [[Inline|inline rolls]] for all dice functions || ScriptCards includes its own dice roll parser, and '''''does not support''''' [[Inline|inline rolls]]. '''''Note: As of version 1.2.3, ScriptCards will parse [[Inline|inline rolls]], inserting their final value in the place of the roll in the macro, but they are not part of or parsed by the built-in roll parser'''''<br />
|-<br />
| PowerCards RollIDs (often mistaken for variables) are assigned by analyzing the results of an inline roll, and cannot be referenced in other rolls, so you can't roll a <code>1d4</code> and then roll a <code>1d20</code> and add the <code>1d4</code> result because all of the rolls happen on the chat server before PowerCards gets the macro text. || ScriptCards supports two types of variables: <code>Roll Variables</code> and <code>String Variables</code>. Because ScriptCards uses its own roll parser and is not dependent upon the chat server, rolls and their results can be used in other rolls, math functions, output, etc.<br />
|}<br />
<br />
== Example Scripts ==<br />
<br />
'''''Note: The features available in ScriptCards have changed drastically since these examples were written. While these should still work, there are in many cases better ways to do things using language features introduces after these were constructed. Please see the [https://github.com/kjaegers/ScriptCards/tree/main/ScriptExamples Script Examples] section of the official ScriptCards GitHub repository for more updated script examples.<br />
<br />
Below are some sample scripts that utilize the various statement types in ScriptCards:<br />
<br />
=== Divine Smite ===<br />
<br />
This script will prompt the user for a spell slot level to expend on a divine smite. It will check the target's npc_type to see if it is an Undead or Fiend, which adds an additional d8 to the smite roll.<br />
<br />
[[File:ScriptCards Divine Smite.png|Divine Smite Script Output]]<br />
<br />
<pre><br />
!scriptcard {{<br />
--#title|Divine Smite<br />
--=DiceCount|?{Spell Slot Level?|1|2|3|4|5|6|7|8|9} + 1<br />
--=IsFiendOrUndead|0<br />
--?"@{target|npc_type}" -inc fiend|>IsBoosted<br />
--?"@{target|npc_type}" -inc undead|>IsBoosted<br />
--=TotalDice|[$DiceCount] + [$IsFiendOrUndead]<br />
--=SmiteRoll|[$TotalDice]d8<br />
--#emoteText|@{selected|token_name} smites @{target|token_name}<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
--+Smite|deals [$SmiteRoll] radiant damage.<br />
--X|<br />
<br />
--:IsBoosted|<br />
--=IsFiendOrUndead|1<br />
--<|<br />
}}<br />
</pre><br />
<br />
==== How It Works ====<br />
<br />
The first line sets the "title" card parameter to "Divine Smite".<br />
<br />
Line 2 Shows a query to the user asking for the spell slot level, adds one and stores the value in the "DiceCount" Roll Variable. The query/dropdown is generated by the chat server prior to the script being executed.<br />
<br />
Line 3 defaults the "IsFiendOrUndead" Roll Variable to 0.<br />
<br />
Lines 4 and 5 compare the target's "npc_type" attribute (passed by the chat server as text) to see if they include either "undead" or "fiend". If true, the IsBoosted subroutine will be called. No parameters are passed to this subroutine.<br />
<br />
Line 6 sets the "TotalDice" variable to the base (DiceCount) number plus the IsFiendOrUndead number, which will be a 0 or a 1.<br />
<br />
Line 7 calculates "SmiteRoll" by rolling a number of d8 equal to the "TotalDice" value.<br />
<br />
Lines 8-10 set the parameters for the emote, which appears above the card content. By setting the sourceToken and the targetToken, their icons will appear in the emote surrounding the text describing the action.<br />
<br />
Line 11 is the only line that actually produces output on the card. It results in "Smite deals # radiant damage".<br />
<br />
Line 12 ends the script execution, preventing the script from continuing and running the subroutines out of context.<br />
<br />
Lines 14-16 are the IsBoosted subroutine, starting with the :IsBoosted label. The IsFiendOrUndead variable is set to 1, and a return from subroutine is executed.<br />
<br />
=== Magic Missile ===<br />
<br />
This script demonstrates using a loop and calling a subroutine to fire a number of missiles determine by the spell slot level used to cast the spell.<br />
<br />
[[File:ScriptCards_MagicMissile_Fixed.png|Magic Missile Script Output]]<br />
<br />
<pre><br />
!scriptcard {{ <br />
--#title|Magic Missile<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
--=MissileCount|?{Spell Slot Level?|1|2|3|4|5|6|7|8|9} + 2<br />
--=DisplayCount|1<br />
--=MissileDamage|0<br />
--#leftsub|Slot level ?{Spell Slot Level?}<br />
--#rightsub|Ranged Attack<br />
--#emoteText|Fred uses a level ?{Spell Slot Level?} spell slot to fire [$MissileCount.Total] missiles of magical force!<br />
--:MissileLoop|<br />
-->FireMissile|<br />
--=DisplayCount|[$DisplayCount] + 1<br />
--?[$DisplayCount] -le [$MissileCount]|MissileLoop<br />
--+Total|Total damage is [$MissileDamage]<br />
--X|<br />
<br />
--:FireMissile|<br />
--=ThisMissile|1d4 + 1<br />
--=MissileDamage|[$MissileDamage] + [$ThisMissile]<br />
--+Missile|[$DisplayCount.Total] Hits for [$ThisMissile] [b]force[/b] damage<br />
--<|<br />
}}<br />
</pre><br />
<br />
==== How It Works ====<br />
<br />
Lines 1-3 set the card title, the source token and the target token. Setting these tokens causes their icons/avatars to appear in the Emote section of the card.<br />
<br />
Line 4 asks the user what spell slot level they wish to use to cast magic missile. The number of missiles fired is equal to 2 plus the spell level, and this is stored in the MissileCount variable.<br />
<br />
Line 5 stores a 1 in the DisplayCount variable. This will be used to control the loop to determine the number of missiles fired and the missile number when displaying damage rolls.<br />
<br />
Line 6 initializes MissileDamage to 0<br />
<br />
Line 7 sets the left subtitle to the text "Slot Level #", where # is the spell slot level being used.<br />
<br />
Line 8 sets the right subtitle to the text "Ranged Attack".<br />
<br />
Line 9 sets the emoteText parameter with a description of the action, including the slot level and number of missiles fired.<br />
<br />
Line 10 is a label for the missile firing loop<br />
<br />
Line 11 Calls the "FireMissile" subroutine<br />
<br />
Line 12 increases the DisplayCount variable by 1<br />
<br />
Line 13 Checks to see if there are still missles to fire (DisplayCount <= MissileCount) and if so branches to MissileLoop<br />
<br />
Line 14 Displays the total damage dealt by the spell.<br />
<br />
Line 15 stops execution of the script to prevent out of context execution of the subroutine.<br />
<br />
Lines 76-21 are the FireMissile subroutine, beginning with the FireMissile label. The 1d4+1 is rolled and assigned to "ThisMissile". The result is added to the existing MissileDamage total, and a line for the current missile is displayed with the missile number and the damage for the missile.<br />
<br />
=== Longsword Attack ===<br />
<br />
This script demonstrates a standard 5E D&D melee weapon attack, including detection of misses, fumbles, hits, and critical hits. If installed, alterbars is used to decrement the target's BAR3 value by the damage dealt.<br />
<br />
[[File:ScriptCards Longsword.png|Longsword Script Output]]<br />
<br />
<pre><br />
!scriptcard {{<br />
--#title|Longsword<br />
--#leftsub|Melee Attack<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
--#emoteText|@{selected|token_name} attacks @{target|token_name}<br />
--=TargetAC|@{target|npc_ac}<br />
--?[$TargetAC.Total] -gt 0|DoneWithAC<br />
--=TargetAC|@{target|ac}<br />
--:DoneWithAC|<br />
--=AttackRoll|1d20 + @{selected|strength_mod} [STR] + @{selected|pb} [PROF]<br />
--+Attack|@{selected|token_name} rolls [$AttackRoll] vs AC [$TargetAC].<br />
--?[$AttackRoll.Base] -eq 20|Crit<br />
--?[$AttackRoll.Base] -eq 1|Fumble<br />
--?[$AttackRoll.Total] -ge [$TargetAC.Total]|Hit<br />
--+Miss|The attack missed.<br />
--^Final|<br />
<br />
--:Fumble|<br />
--+Fumble!|The attack went horribly wrong.<br />
--^Final|<br />
<br />
--:Hit|<br />
--=Damage|1d8 + @{selected|strength_mod} [STR]<br />
--+Hit!|The attack hit @{target|token_name} for [$Damage] slashing damage.<br />
--@alter|_target|@{target|token_id} _bar|3 _amount|-[$Damage]<br />
--^Final|<br />
<br />
--:Crit|<br />
--=Damage|1d8 + @{selected|strength_mod} [STR] + 1d8 [CRIT]<br />
--+Critical Hit!|The attack hit @{target|token_name} for [$Damage] slashing damage.<br />
--@alter|_target|@{target|token_id} _bar|3 _amount|-[$Damage]<br />
<br />
--:Final|<br />
}}<br />
</pre><br />
<br />
==== How it Works ====<br />
<br />
In lines 1-5, we set the title, subtitle, and emote text along with the tokens for the emote area.<br />
<br />
Lines 6-9 allow us to determine the AC of the target. On the 5E Roll20 sheet, NPCs armor class is stored in "npc_ac", while PCs armor class is in "ac". First we grab npc_ac and if it is zero, we check AC.<br />
<br />
Line 10 rolls the attack roll, rolling 1d20 and adding the attacker's strength modifier and proficiency bonus<br />
<br />
Line 11 displays the result of the attack roll on the card<br />
<br />
Lines 12-14 determine what kind of result the attack had. If the .Base value of the roll was 20, we branch to "Crit". If it was 1, we branch to "Fumble". If the .Total value of the roll was greater than or equal to the AC that was determined in Lines 6-9, we branch to Hit.<br />
<br />
Assuming we didn't branc anywhere, the result of the attack was a miss, so we display that on line 15 and then branch to "Final"<br />
<br />
This is followed by three branch segments, :Fumble, :Hit, and :Crit. A fumble displays a text message and branches to :Final.<br />
<br />
On a hit or a crit, we roll Damage (adding additional damage dice on a crit). We display a "Hit!" or "Critical Hit!" message and then make an API call to AlterBars, passing it the token id, bar we want to modify (3 in this case), and the amount we want to modify by the Damage value.<br />
<br />
=== Party Health Status ===<br />
<br />
This example calculates the current Hit Points remaining and HP percentage for each character and creates a color-coded display with the current party status.<br />
<br />
[[File:ScriptCards Party Health.png]]<br />
<br />
<pre><br />
!scriptcard {{<br />
--#title|Party Status<br />
--#titleCardBackground|#33CC33<br />
--#oddrowbackground|#bfee90<br />
--#evenrowbackground|#90eebf<br />
-->HealthCheck|@{Quej Grastra|character_id}<br />
-->HealthCheck|@{Brim Cheuto|character_id}<br />
-->HealthCheck|@{Odug Ututees|character_id}<br />
--X|End of card Execution<br />
<br />
--:HealthCheck|<br />
--=HealthPerc|[*[%1%]:hp] / [*[%1%]:hp^] * 100 \ 1<br />
--=HealthColor|000000<br />
--?[$HealthPerc.Total] -gt 50|HealthSkip<br />
--=HealthColor|FF0000<br />
--:HealthSkip|<br />
--+[*[%1%]:character_name]|has [#[$HealthColor.RollText]][*[%1%]:hp] of [*[%1%]:hp^][/#] HP [R]([$HealthPerc.Total]%)[/R]<br />
--<|End of HealthCheck<br />
}}<br />
</pre><br />
<br />
==== How it Works ====<br />
<br />
Lines 1-4, we set the card title, and set the title background and row background colors to shades of green.<br />
<br />
Lines 5-7 make gosub calls the the "HealthCheck" subroutine, passing in the character ID of each of the named characters (these are the names of the characters in my test game)<br />
<br />
Line 8 terminates the script execution.<br />
<br />
The remaining lines of the script are the HealthCheck subroutine, which works like this:<br />
<br />
Line 10 is the subroutine label (:HealthCheck)<br />
<br />
Line 11 uses the character id passed as a parameter and combines it with character attribute lookup *(...) to retrieve the value of "hp" and "hp<nowiki>^</nowiki>" for the character. The <nowiki>^</nowiki> character is used to specify that we want the MAX value for this attribute for the second call. We divide these two numbers and multiple by 100 to get a percentage. Finally, we use integer division by 1 to round the percentage and drop the decimals. The end result gets stored in the HealthPerc roll variable.<br />
<br />
Line 12 defaults to color of the health text to black<br />
<br />
Line 13 check to see if the health percentage is greater than 50. If so, it branches to HealthSkip, preventing the script from executing line 13.<br />
<br />
Line 14 sets the color of the health text to red<br />
<br />
Line 15 is the label that will be branched to from Line 13 to skip the red coloring<br />
<br />
Line 16 again uses character attribute substitution and the passed parameter value to output a display line containing the character name, the colorized health total, and the percentage value. The percentage is right-justified.<br />
<br />
Line 17 returns from the HealthCheck subroutine.<br />
<br />
=== Expanded Magic Missile Script ===<br />
<br />
This is the expanded and enhanced version of the Magic Missile script covered in {{yt|watch?v=u50xvNzS9Zk | this video}}. It includes visual and audio effects, checking and deducting spell slots, and applying damage using either Token-Mod or Alterbars.<br />
<br />
<pre><br />
!scriptcard {{ <br />
--#title|Magic Missile<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
<br />
-->GetAndCheckSlotInformation|<br />
<br />
--=MissileCount|[$SlotLevel] + 2<br />
--=DisplayCount|1<br />
--=MissileDamage|0<br />
--#leftsub|Slot level [$SlotLevel]<br />
--#rightsub|Ranged Attack<br />
--#emoteText|@{selected|character_name} uses a level [$SlotLevel.Total] spell slot to fire [$MissileCount.Total] missiles of magical force!<br />
<br />
--:MissileLoop|<br />
-->FireMissile|<br />
--=DisplayCount|[$DisplayCount] + 1<br />
--?[$DisplayCount] -le [$MissileCount]|MissileLoop<br />
--+Total|Total damage is [$MissileDamage]<br />
-->DeductSpellSlot|<br />
--#rightsub|Level [$SlotLevel] Left: [$SlotsRemaining] <br />
-->PlayEffects|none;burst-smoke;beam-magic;spell_01<br />
-->ApplyDamageTokenmod|@{target|token_id};3;-[$MissileDamage]<br />
-->ApplyDamageAlterbars|@{target|token_id};3;-[$MissileDamage]<br />
--X|<br />
<br />
--:FireMissile|<br />
--=ThisMissile|1d4 + 1<br />
--=MissileDamage|[$MissileDamage] + [$ThisMissile]<br />
--+Missile|[$DisplayCount.Total] Hits for [$ThisMissile] [b]force[/b] damage<br />
--<|<br />
<br />
--:GetAndCheckSlotInformation|<br />
--=SlotLevel|?{Spell Slot Level?|1|2|3|4|5|6|7|8|9}<br />
--=SlotsTotal|[*S:lvl[$SlotLevel]_slots_total]<br />
--=SlotsExpended|[*S:lvl[$SlotLevel]_slots_expended]<br />
--?[$SlotsExpended.Total] -ge [$SlotsTotal.Total]|NoSlotsLeft<br />
--<|<br />
<br />
--:NoSlotsLeft|<br />
--+|[*S:character_name] has no level [$SlotLevel.Total] spell slots available.<br />
--X|<br />
<br />
--:DeductSpellSlot|<br />
--=SlotsExpended|[$SlotsExpended] + 1<br />
--@setattr|_charid [*S:character_id] _lvl[$SlotLevel]_slots_expended|[$SlotsExpended] _silent<br />
--=SlotsRemaining|[$SlotsTotal] - [$SlotsExpended]<br />
--<|<br />
<br />
--:PlayEffects|Parameters are : source effect; target effect; line effect; sound effect<br />
--vtoken|@{selected|token_id} [%1%]<br />
--vtoken|@{target|token_id} [%2%]<br />
--vbetweentokens|@{selected|token_id} @{target|token_id} [%3%]<br />
--@roll20AM|_audio,play,nomenu|[%4%]<br />
--<|<br />
<br />
--:ApplyDamageTokenmod|Parameters are tokenid;bar#;amount<br />
--@token-mod|_ignore-selected _ids [%1%] _set bar[%2%]_value|[%3%]<br />
--<|<br />
<br />
--:ApplyDamageAlterbars|<br />
--@alter|_target|[%1%] _bar|[%2%] _amount|[%3%]<br />
--<|<br />
}}<br />
</pre><br />
<br />
===Hidden Roll===<br />
<br />
A roll where only the GM sees the result of the roll.<br />
[[File:Scriptcards-hiddenroll.png|right]]<br />
<pre><br />
!script {{<br />
--#title|Stealth Check<br />
--=Roll|1d20 + @{selected|stealth}<br />
--+|@{selected|token_name} attempts to move undetected...<br />
--*GMLine|@{selected|token_name} rolled a [$Roll]<br />
}}<br />
</pre><br />
<br />
===Elsewhere===<br />
* {{fpl|10000297/ Scritpcard API Working and Sharing}}<br />
* [https://gist.github.com/dubzilla1/cba439bd1f47ecdd81d0c79a482c4a91 Pathfinder 2E heal macros]<br />
<br />
[[Category:Featured articles]]</div>5004103https://wiki.roll20.net/Script:ScriptCardsScript:ScriptCards2022-02-11T11:38:58Z<p>5004103: /* Character/Token Attributes */</p>
<hr />
<div>{{revdate}}<br />
== Introduction ==<br />
'''ScriptCards''' provides a script interpreter that can be used to create powerful macros that display the results of player/NPC actions, or display other information in a pleasing visual format in your game's {{Text Chat}}. The scripting language contains variables (both dice-roll (enhanced numerics) and strings) as well, conditionals, branching, subroutines with parameters, and a set of built-in functions to simplify working with Roll20 information.<br />
{{script overview<br />
|name=ScriptCards<br />
|author=[[Kurt J.]]<br />
|code=ScriptCards<br />
|version=1.4.10<br />
|lastmodified=2021-12-04}}<br />
ScriptCards is not game-system specific, and can be used with any system/sheet. Near the end of this Wiki there is a section set aside for libraries that can implement system-specific tasks, with the hope that enthusiasts playing particular systems will create and share utility functions that can be utilized by the wider community.<br />
<br />
The default display style for ScriptCards output is similar to the format used to document player and NPC abilities in Dungeons and Dragons 4th Edition, but does not have any system ties to D&D4E.<br />
<br />
Current OneClick Version : 1.4.10<br />
'''''Note:''''' '''As of 2021-12-04, ScriptCards 1.4.10 has been submitted for OneClick update. The documentation below is in the process of being updated for 1.4.10.<br />
<br />
Current Development Version : 1.5.2<br />
<br />
'''''<big>Critically Important: ScriptCards does not use/parse [[Inline|inline rolls]]. ScriptCards includes its own built-in dice roll parser to allow for the use of variables inside dice rolls. As of version 1.2.3, ScriptCards will now take inline rolls and substitute the total result value in statement strings, meaning that you can utilize inline rolls but ScriptCards will only see the result of the roll, and not parse the roll components itself.</big>'''''<br />
{{#evp:youtube|hyR7Jnq4mQM|[[Script:ScriptCards|ScriptCards]] Introduction|right|650}}<br />
* {{fpl|9752053/ ScriptCards thread}}<br />
** {{fpl|10000297/ Scritpcard API Working and Sharing}}<br />
* {{repo|kjaegers/ScriptCards/tree/main/ScriptCards_API ScriptCards_API}} - GitHub repository for source before the one-click version is updated.<br />
* {{repo|kjaegers/ScriptCards/tree/main/ScriptExamples ScriptCards Samples}} - Branch of the GitHub repo that contains sample scripts.<br />
* {{yt.be|hyR7Jnq4mQM ScriptCards Intro}} 45min, Jan 2021<br />
* {{yt.be|u50xvNzS9Zk ScriptCards Magic Missile Deep Dive}} 39min, Feb 2021<br />
__TOC__<br />
=== Is ScriptCards Related to [[PowerCards]]? ===<br />
<br />
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.<br />
<br />
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 ({{code|name}}, {{code|leftsub}}, {{code|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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
Check the '''[[#What to Know if you are Coming from PowerCards|What to Know if you are Coming from PowerCards]]'''-section for a comparison table between the two scripts.<br />
<br />
=== What is a ScriptCard Script ===<br />
<br />
A ScriptCard Script is text written into the {{Text Chat}} (either typed directly, pasted, or run via a macro) that will produce a card of information in the [[Text Chat|chat window]]. A ScriptCard Script is composed of an [[API]] command: <code><nowiki>!scriptcard {{ }}</nowiki></code> enclosing any number of lines that determine the output that will be added to the card. At it simplest, the following macro:<br />
<br />
<pre>!scriptcard {{ }}</pre><br />
<br />
Will produce just a title card that displays “ScriptCards” as the name:<br />
<br />
[[File:Scriptcard blank.png]]<br />
<br />
Of course, this is just the simplest type of macro and isn’t very useful. In order to produce useful output, we need to include lines between the <code><nowiki>{{</nowiki></code> and <code><nowiki>}}</nowiki></code> that direct the API script as to what it should do.<br />
<br />
== Structure of a ScriptCard Line ==<br />
<br />
All ScriptCard lines begin with two dashes, followed by an ''statement identifier character'' that lets ScriptCards what type of line it is. There are several of these, and they are detailed in the next section. After the line type identifier, a Tag name 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.<br />
<br />
Following the Tag is a vertical bar, and then the content of the line itself. Again, each type of line might interpret this content differently.<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Identifier !! Statement Type !! Tag !! Content !! Notes<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--/</nowiki> || Comment || unused || unused || The <code>--/</code> 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--#</nowiki> || 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").<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--+</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--=</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--&</nowiki> || Assign String 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. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--@</nowiki> || 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 (i.e., [[TokenMod|!token-mod]], or [[ChatSetAttr|!setattr]], etc.)<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--:</nowiki> || 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<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--^</nowiki> || Branch To || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--></nowiki> || Call Procedure || 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<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--<</nowiki> || 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.<br />
|- <br />
| style="white-space:nowrap" | <nowiki>--?</nowiki> || Conditional Branch || Condition to be evaluated || True Branch Label<nowiki>|</nowiki>False Branch Label || The condition will be evaluated and execution will jump to one of the two indicated branches (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 included a semicolon separated list of parameters. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--s</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--l</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--v</nowiki> || 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+'''''<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--a</nowiki> || Play Audio Track || Unused || Jukebox track name (case sensitive) || Plays an audio track by name from the Roll20 jukebox. '''''Requires v1.5.2+'''''<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--e</nowiki> || Echo to Chat || Name to send chat command as || Chat message to send || Variable substitution takes place on the tag and content.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--R</nowiki> || Retrieve Repeating Section Row information || "find", "first", or "next" || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--~</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--c</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--i</nowiki> || Information Request || User Prompt;Button Caption || InfoType;VariableName;ParameterText || See full documentation below.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--d</nowiki> || 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. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--%</nowiki> || 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. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--*</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--!</nowiki> || Object Modification || <objectType>:<objectId> || setting:value|setting:value|setting:value... || Set properties of tokens/characters or character attributes ('''''v1.5.0+ required''''')<br />
|}<br />
<br />
== ScriptCard Statement Type Details ==<br />
The sections below detail the individual statement types supported by ScriptCards<br />
<br />
=== Comment (--/) ===<br />
<br />
A --/ statement is ignored by the ScriptCards parser. You can use this type of statement to add comments and informational text to your script. <br />
<br />
Example:<br />
<pre><br />
!script {{<br />
--/|Script Name : Fireball<br />
--/|Purpose : Allow the player to cast a fireball and blow stuff up!<br />
.<br />
.<br />
.<br />
}}<br />
</pre><br />
<br />
=== Set Parameter (--#) ===<br />
<br />
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.<br />
<br />
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.<br />
<br />
'''''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.'''''<br />
<br />
Examples:<br />
<pre><br />
--#title|Magic Missile<br />
--#leftsub|Level 1 Spell<br />
--#rightsub|Force Damage<br />
</pre><br />
<br />
The three examples above set the “title”, “leftsub”, and “rightsub” values for the card to the content value for the line. <br />
<br />
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.<br />
Settings Lines do not produce output lines on the card.<br />
<br />
The following settings are available (note that parameter names are ''not'' case sensitive):<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Name !! Effect/Use !! Default Value !! Type<br />
|-<br />
| 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<br />
|-<br />
| allowplaintextinrolls || If set to a non-zero value, plain character text in rolls will be copied to the roll text || 0 || Per-Line<br />
|-<br />
| bodyFontFace || Name of the font used in the card rows || Helvetica || Global<br />
|-<br />
| bodyFontSize || Size of the text in the card rows || 14px || Global<br />
|-<br />
| bodybackgroundimage || Specify an image (content for a CSS background-image tag) for the body area || none || Global<br />
|-<br />
| buttonBackground || Background color for buttons created with [button][/button] || #1C6EA4 || Per-Line<br />
|-<br />
| buttonBackgroundImage || A CSS specifier for a background image to use for buttons (i.e. url(...);) || empty || Per-Line<br />
|-<br />
| buttonBorderColor || Border (outline) color for buttons created with [button][/button] || #999999 || Per-Line<br />
|-<br />
| buttonFontFace || Font Family specifier for captions on buttons created with [button][/button] || Tahoma || Per-Line<br />
|-<br />
| buttonFontSize|| Text size for captions on buttons created with [button][/button] || x-small || Per-Line<br />
|-<br />
| buttonTextColor|| Text color of labels on buttons created with [button][/button] || #FFFFFF || Per-Line<br />
|-<br />
| 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<br />
|-<br />
| deferralcharacter || Changes the meta script deferral sequence to the specified value || ^ || Per-Line<br />
|-<br />
| diceFontColor|| Color of the dice created with the [d4] [d6], etc. formatting markers || #1C6EA4 || Per-Line<br />
|-<br />
| dicefontsize || Size of the dice created with the [d4] [d6], etc. formatting markers || 3.0em || Per-Line<br />
|-<br />
| 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<br />
|-<br />
| disablerollprocessing || If set to a non-zero value, --= lines will not process dice rolls strings || 0 || Per-Line<br />
|-<br />
| emoteBackground || Background color of the emote area || #f5f5ba || Global<br />
|-<br />
| emoteFont || Name of the font used in emote area (above the title of the output card) || Georgia || Global<br />
|-<br />
| emoteFontColor || Color of the font in the emote area || None (Empty) || Global<br />
|-<br />
| emoteFontSize || Size of the font used in the emote area || 14px || Global<br />
|-<br />
| emoteFontWeight || Font weight for the font in the emote area || bold|| Global<br />
|-<br />
| emoteState || If set to anything other than "visible", the emote portion of the card will not be displayed || visible || Global<br />
|-<br />
| emoteText || Text to display in the emote portion of the card || None (Empty) || Global<br />
|-<br />
| emotefont || Name of the font used in the emote text area || font-family: Georgia, serif; font-weight: bold; || Global<br />
|-<br />
| evenRowBackground || Hex code for the background color for even rows || #eeeeee || Per-Line<br />
|-<br />
| evenRowFontColor || Hex code for the text color for even rows || #000000 || Per-Line<br />
|-<br />
| evenrowbackgroundimage || Specify an image (content for a CSS background-image tag) for the even card rows || none || Per-Line<br />
|-<br />
| executionlimit || Maximum number of script lines the interpreter will try to execute. This prevents "infinite loop" sandbox crashes || 40000 || Global<br />
|-<br />
| hideCard || If set to any non-default value, the entire card output will be suppressed || 0 || Global<br />
|-<br />
| 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<br />
|-<br />
| 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<br />
|-<br />
| lineheight || Vertical size of each line on the output card || normal || Per-Line<br />
|-<br />
| nominmaxhighlight || If set to anything other than "0", rolls will not display crit/fumble/mixed highlight colors. || 0 || Per-Line<br />
|-<br />
| norollhighlight || If set to anything other than "0", rolls will not be formatted (plain numbers) but will still get a tooltip with details ('''''v1.3.6b+''''') || 0 || Per-Line<br />
|-<br />
| oddRowBackground || Hex code for the background color for even rows || #d0e4f5 || Per-Line <br />
|-<br />
| oddRowFontColor || Hex code for the text color for odd rows || #000000 || Per-Line<br />
|-<br />
| oddrowbackgroundimage || Specify an image (content for a CSS background-image tag) for the odd crd rows || none || Per-Line<br />
|-<br />
| reentrant || Used to name a script for rentrant button use || 0 || Global<br />
|-<br />
| 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)0 || Global<br />
|-<br />
| rollhilightcolorboth || Background box hilight color if both a 1 and a max on the die are rolled ('''''1.4.4+''''') || #8FA4D4 || Per-Line<br />
|-<br />
| rollhilightcolorcrit || Background box hilight color if the maximum number on the die was rolled ('''''1.4.4+''''') || #88CC88 || Per-Line<br />
|-<br />
| rollhilightcolorfumble || Background box hilight color if a 1 was rolled ('''''1.4.4+''''') || #FFAAAA || Per-Line<br />
|-<br />
| rollhilightcolornormal || Background box hilight color if neither a 1 or a max on the die are rolled ('''''1.4.4+''''') || #FFFEA2 || Per-Line<br />
|- <br />
| rollhilightlineheight || Determines the height of the hilight box placed around roll results ('''''1.4.2+''''') || 1.0em || Per-Line<br />
|-<br />
| roundUp || If set to a non-default value, integer division will round up instead of down || 0 || Per-Line<br />
|-<br />
| showfromfornonwhispers || If set to a non-zero value, will include the sender on cards that aren't whispered || 0 || Global<br />
|-<br />
| 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<br />
|-<br />
| subtitleFontColor || Color of the text in the subtitle areas || #FFFFFF || Global<br />
|-<br />
| subtitleFontFace || Name of the font used on the subtitle sections || Tahoma || Global<br />
|-<br />
| subtitleFontSize || Size of the subtitle font || 13px || Global<br />
|-<br />
| subtitleSeperator || The character(s) that will be placed between leftsub and rightsub || <nowiki>&#x2666</nowiki>; || Global<br />
|-<br />
| tableBorderRadius || CSS specifier for how rounded the borders of the output card are. Use "0px;" for square borders || 6px; || Global<br />
|-<br />
| tableShadow || CSS specifier for the drop shadow under the output card || 5px 3px 3px 0px #aaa; || Global<br />
|-<br />
| tablebgcolor || Background color of the whole card. '''''Normally not visible''''' || #EEEEEE || Global<br />
|-<br />
| tableborder || Color of the border that surrounds the whole card || 2px solid #000000; || Global<br />
|-<br />
| 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<br />
|-<br />
| timezone || IANA Specifier for the local time zone, used in system/date functions || America/New_York || Per-Line<br />
|-<br />
| title || Text displayed in the title area of the card || ScriptCards || Global<br />
|-<br />
| titleCardBackground || A hex color code representing the background color of the title area. || #1c6ea4 || Global<br />
|-<br />
| titleFontColor || Color of the text on the card title || #FFFFFF || Global<br />
|-<br />
| titleFontFace || Name of the font used on the title area || Contrail One || Global<br />
|-<br />
| titleFontLineHeight || Line spacing on the title area || 1.2em || Global<br />
|-<br />
| titleFontSize || Size of the title font || 1.2em || Global<br />
|-<br />
| titlecardbackgroundimage || Specify an image (content for a CSS background-image tag) for the title card area || none || Global<br />
|-<br />
| titlecardbottomborder || Border CSS specifier for the bottom of the title card area || 2px solid #444444; || Global<br />
|-<br />
| titlecardgradient || If set to non-zero value, will place a vertical gradient on the title card area || 0 || Global<br />
|-<br />
| usehollowdice || If set to a non-zero value, the hollow/outline versions of the dice fonts will be used || 0 || Per-Line<br />
|-<br />
| whisper|| Comma separated list of who to whisper the output to. Use "gm" for [[GM|GMs]] and "self" for the sender || none || Global|}<br />
|}<br />
<br />
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). <br />
<br />
''Setting Lines do not produce output lines on the card''<br />
<br />
=== Direct Output (--+) ===<br />
<br />
A direct output line display 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.<br />
<br />
Examples of Direct Output lines:<br />
<pre><br />
--+Hello|World<br />
--+Attack|The monster rolls [$Attack] to hit!<br />
--+Damage|@{target|token_name} is hit for [$Damage] [#3333AA][b]frost[/b][/#] damage.<br />
</pre><br />
<br />
Direct Output lines support inline formatting, roll variable replacement, character attribute references, and procedure variables.<br />
<br />
=== GM Output (--*) ===<br />
<br />
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. <br />
<br />
Example:<br />
<pre><br />
--+PlayerLine|This line is shown on the public card<br />
--*GMLine|This line will only be shown to GMs, on a separate card.<br />
</pre><br />
<br />
=== Roll Variable Assignment (--=) ===<br />
<br />
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.<br />
<br />
'''''All components of a roll equation should be separated with spaces.'''''<br />
<br />
Examples:<br />
<pre><br />
--=MissileDamage|1d4 + 1<br />
--=Attack|1d20 + @{selected|strength_mod} [STR] + @{selected|pb} [PROF]<br />
</pre><br />
<br />
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. Text enclosed in square brackets ([]) is considered "flavor text" and will be added to the result text but does not impact the roll result.<br />
<br />
The following dice formats are supported:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Format Pattern !! Example !! Description<br />
|-<br />
| XdY || 3d8 || Simple format. Roll a Y-sided die X times<br />
|-<br />
| XdYkhZ || 2d20kh1 || Roll Y-sided die X times and keep the highest Z number of dice<br />
|-<br />
| XdYklZ || 4d6kl3 || Roll Y-sided die X times and keep the lowest Z number of dice <br />
|-<br />
| XdY>Z || 5d6>3 || Roll Y-sided die X times and count a 1 for each roll greater than Z <br />
|-<br />
| XdY<Z || 5d6<3 || Roll Y-sided die X times and count a 1 for each roll less than Z <br />
|-<br />
| 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<br />
|-<br />
| 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<br />
|-<br />
| 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)<br />
|-<br />
| 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<br />
|-<br />
| 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).<br />
|-<br />
| 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.<br />
|-<br />
| 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. ('''''v1.5.1''''')<br />
|}<br />
<br />
The following operators are supported in a roll equation:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Operator !! Operation<br />
|-<br />
| + || Addition <br />
|-<br />
| - || Subtraction <br />
|-<br />
| * || Multiplication <br />
|-<br />
| / || Division <br />
|-<br />
| \ || Integer Division (Rounds down) <br />
|-<br />
| % || Modulo (Remainder of Divison)<br />
|}<br />
<br />
Roll Variables can be accessed at any time after they have been created by using the [$VariableName] format, with the following optional modifiers:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Modifier !! Meaning<br />
|-<br />
| No modifier || In a Direct Output Line (<nowiki>--+</nowiki>) 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<br />
|-<br />
| .Total || The end result of the roll equation as an unformatted number <br />
|-<br />
| .Base || The cumulative result of any dice rolled in the Roll Text (Numeric modifiers are not included) <br />
|-<br />
| .Ones || The number of dice in the roll that came up as 1s <br />
|-<br />
| .Aces || The number of dice in the roll that came up as the maximum number on the die <br />
|-<br />
| .Odds || The number of dice in the roll that came up with an odd number <br />
|-<br />
| .Evens || The number of dice in the roll that came up with an even number <br />
|-<br />
| .RollText || The raw text of the roll that was use to generate the results <br />
|-<br />
| .Text || A text representation of the results of the roll, including the numbers rolled for each die <br />
|-<br />
| .tableEntryText || The text portion of the result of a table roll<br />
|-<br />
| .tableEntryImgURL || The image source portion of the result of a table roll<br />
|-<br />
| .tableEntryValue || Numeric value of tableEntryText (via parseInt). If a non-numeric value, will be 0<br />
|-<br />
| .Raw || The total numeric result without any formatting, even if placed somewhere formatting would normally be done. <br />
|}<br />
<br />
Examples:<br />
<pre><br />
--+Total Damage|[$MissileDamage.Total] (roll was 1d4+1)<br />
--+Base Damage|[$MissileDamage.Base] (without the +1)<br />
--=Attack|1d20 + @{selected|strength_mod} [STR] + @{selected|pb} [PROF] + [$BlessBonus] [Bless]<br />
</pre><br />
<br />
In this case, 1d4 will be rolled and stored in “BlessBonus”, which can then be used in the Attack line.<br />
<br />
'''''Mathematical Functions in Roll Expressions '''''<br />
<br />
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:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Expression !! Meaning<br />
|-<br />
| {ABS} || Absolute Value<br />
|-<br />
| {CEIL} || Ceiling value (round up to the next whole number)<br />
|-<br />
| {FLOOR} || Floor value (round down to the next whole number)<br />
|-<br />
| {ROUND} || Round value (round up if the decimal portion is greater than 0.5, otherwise round down) '''Note: As of 1.4.11, ROUND now supports :X as a suffix to round to a given number of decimal places (ie, {ROUND:2}'''<br />
|-<br />
| {NEGATE} || Multiply the value by negative one.<br />
|-<br />
| {SQRT} || Take the square root of the running value.<br />
|-<br />
| {SQUARE} || Square the running value.<br />
|-<br />
| {CUBEROOT} || Take the cube root of the running value.<br />
|-<br />
| {CUBE} || Cube the running value.<br />
|-<br />
| {SIN} || Return the SIN of running value.<br />
|-<br />
| {COS} || Return the COS of running value.<br />
|-<br />
| {TAN} || Return the TAN of running value.<br />
|-<br />
| {ASIN} || Return the ASIN of running value.<br />
|-<br />
| {ACOS} || Return the ACOS of running value.<br />
|-<br />
| {ATAN} || Return the ATAN of running value.<br />
|-<br />
| {MAX:X} || Caps the running value at X. ('''''v1.4.12''''')<br />
|-<br />
| {MIN:X} || If the running value is less than X, set the value to X. ('''''v1.4.12''''')<br />
|-<br />
| {CLAMP:X:Y} || Adjust the running value to remain between X (lower bound) and Y (upper bound) ('''''v1.4.12''''')<br />
|}<br />
<br />
Here are the syntax rules when using the above listed functions:<br />
<br />
Example 1.<br />
<br />
<pre><br />
!script {{<br />
--=output|2.9 {FLOOR}<br />
--+output|[$output]<br />
}}<br />
</pre><br />
<br />
The output from this example is "2".<br />
<br />
Example 2.<br />
<br />
<pre><br />
!script {{<br />
--=output|2.9 {FLOOR} {NEGATE} - 3<br />
--+output|[$output]<br />
}}<br />
</pre><br />
<br />
The output from this example is "-5".<br />
<br />
Basically, a function will use as its input whatever the current "running total" is.<br />
<br />
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.<br />
<br />
<br />
'''''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 <nowiki>[[ ]]</nowiki> 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.<br />
<br />
'''''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.<br />
<br />
'''Rolling on Rollable Tables'''<br />
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.<br />
<br />
''Roll Variable Lines do not produce output lines on the card.''<br />
<br />
=== String Variable Assignment (--&) ===<br />
<br />
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:<br />
<br />
<pre><br />
--&MyText|Hello<br />
</pre><br />
<br />
Here, we assign the text "Hello" to the string variable named MyText. You can also append text to a string variable by prefixing the content with a + sign:<br />
<br />
<pre><br />
--&MyText|+ World<br />
</pre><br />
<br />
If run after the statement above, MyText will now contain "Hello World".<br />
<br />
String variables can be referenced using the syntax [&variablename]<br />
<br />
=== Call API (--@) ===<br />
<br />
ScriptCards can use a Call API instruction to execute other API commands. The Tag contains the API 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 API command is executed.<br />
<br />
Examples:<br />
<pre><br />
--@eh|list<br />
--@alter|_target|@{target|token_id} _bar|3 _amount|-[$Damage]<br />
</pre><br />
<br />
In the first example above, the command <code>!eh list</code> will be executed, calling [[EncounterHelper]]. In the second, {{fpl|1216260/ AlterBars}} is called to modify a token's Bar 3 value.<br />
<br />
'''''Note:''''' When ScriptCards (or any API script) runs other API 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).<br />
<br />
See [[API:Script Index]] for more options.<br />
<br />
=== Branch Label (--:) ===<br />
<br />
A branch label defines a line in your code that can be reached by one of the branching instructions (<nowiki>--^</nowiki>, <nowiki>--></nowiki>, or <nowiki>--?</nowiki>). The Tag serves as the label name, and must be unique on the card.<br />
<br />
The vertical bar (|) separator must be present, but the content portion of the line is unused and can be treated as a comment.<br />
<br />
Examples:<br />
<pre><br />
--:MyLoop|<br />
--:CriticalHit|Will jump here if we roll a critical hit!<br />
</pre><br />
<br />
''A Branch Label line does not produce an output line on the card.''<br />
<br />
=== Branch (--^) === <br />
<br />
A Branch line 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.<br />
<br />
Examples:<br />
<pre><br />
--^MyLoop|Jumps to MyLoop<br />
--^SkipCrit|We didn't crit, so skip the Crit code<br />
</pre><br />
<br />
''A Branch line does not produce an output line on the card.''<br />
<br />
=== Call Procedure (-->) ===<br />
<br />
Similar to a branch, a Call Procedure (sometimes knows 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 (<nowiki>--<</nowiki>) 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 (;).<br />
<br />
Examples:<br />
<pre><br />
-->FixFormat|#3333FF;#999999<br />
</pre><br />
<br />
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%].<br />
<br />
=== Return (--<) ===<br />
<br />
A return instruction marks the end of a Gosub procedure. 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.<br />
<br />
Examples:<br />
<pre><br />
--<|<br />
--<|End of MySub<br />
</pre><br />
<br />
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.<br />
<br />
=== Conditional Statement (--?) ===<br />
<br />
A conditional statement contains some equation in the Tag that will be evaluated. '''''If any part of the comparison can/does contain a space, it needs to be surrounded by double quotes'''''<br />
<br />
Based on the true/false result of the evaluation, one of two execution paths will be taken. These execution paths are detailed in the content section of the statement. The "if true" path is specified first (directly after the vertical bar), and the "if false" path is specified after it, also separated by a vertical bar.<br />
<br />
Example:<br />
<pre><br />
--?[$AttackRoll.Total] -ge [$TargetAC]|Hit|Miss<br />
</pre><br />
<br />
'''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.'''<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Branch Format !! Meaning<br />
|-<br />
| Label || If just a label is specified, execution will branch to that label when the comparison is matched.<br />
|-<br />
| >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 <br />
|-<br />
| =VariableName || The roll variable "VariableName" will be assigned the value following a semicolon (for example, the code "=Roll;1d20" will assign the value "1d20" to a variable named "Roll", if the condition is true).<br />
|-<br />
| &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).<br />
|-<br />
| % or %! || The current for...next loop will perform the "next" action (%) or will break out (%!) <br />
|-<br />
| [ || Code block (see below)<br />
|}<br />
<br />
Examples:<br />
<pre><br />
--?[$AttackRoll.Base] -eq 20|CriticalHit<br />
--?[$AttackRoll.Base] -eq 1|>Fumble;@{selected|dexterity_mod}<br />
--?"@{target|npc_type}" -inc "undead"|&MonsterType;Undead|&MonsterType;Not Undead<br />
--?[$Attack.Total] >= [$ArmorClass]|>Hit|>Miss<br />
</pre><br />
<br />
In the first example, if the Base value of AttackRoll is a 20 (natural 20 on the die) execution will branch to the CriticalHit label.<br />
<br />
In the second example, 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%].<br />
<br />
The third example looks for the word "undead" in the npc_type attribute of the targeted character. If it exists in the text, the MonsterType string variable will be set to "Undead", otherwise it will be set to "Not Undead". <br />
<br />
The final example would call 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.<br />
<br />
''Text that does/may contain a space should be enclosed in double quotes.''<br />
<br />
The following comparison operators are available:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Comparator !! Meaning<br />
|-<br />
| -eq || Equal To <br />
|-<br />
| -eqi || Case insensitive Equal To <br />
|-<br />
| -ne || Not Equal To <br />
|-<br />
| -nei || Case insensitive Not Equal To <br />
|-<br />
| -gt || Greater Than <br />
|-<br />
| -ge || Greater Than or Equal To <br />
|-<br />
| -lt || Less Than <br />
|-<br />
| -le || Less Than or Equal To <br />
|-<br />
| -inc || Includes (text strings). <br />
|-<br />
| -ninc || Does Not Include (text strings). <br />
|}<br />
<br />
Multi-part conditionals are supported with -and and -or as separators. For example:<br />
<br />
<pre><br />
--?[$Attack.Total] -ge @{target|npc_ac} -and [$Attack.Base] -ne 20|HitButNotCrit<br />
</pre><br />
<br />
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):<br />
<br />
true AND false OR true<br />
<br />
Will be evaluated as true. The first two (true and false) will be false, but then false OR true will be true.<br />
<br />
Conversely:<br />
<br />
true or false and false<br />
<br />
Will be false, because the first true and false will evaluate to true, and then true and false will be false.<br />
<br />
'''CODE BLOCKS'''<br />
<br />
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.<br />
<br />
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:<br />
<br />
<pre><br />
!script {{<br />
--=Roll|1d2<br />
--+Roll|[$Roll]<br />
--?[$Roll.Total] -eq 2|[<br />
--&Value|Yep!<br />
--+|We are inside the TRUE portion of the block<br />
--]|[<br />
--&Value|Nope<br />
--+|We are inside the FALSE portion of the block<br />
--]|<br />
--+After|the blocks!<br />
--+Value|[&Value]<br />
}}<br />
</pre><br />
<br />
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 --]|. <br />
<br />
At this time, blocks cannot be nested, and can only be created as part of a conditional (--[ is not a valid statement type)<br />
<br />
''A conditional statement does not produce a line of output on the card.''<br />
<br />
=== Case Statement (--c) ===<br />
<br />
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 (:). Each match condition includes a branch label that will be used if the test value matches the item. 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:<br />
<br />
<pre><br />
!script {{<br />
--#title|Case Statement Testing<br />
--=Roll|1d4<br />
--C[$Roll.Total]|1:>One;[$Roll]|2:>Two;[$Roll]|3:>Three;[$Roll]|4:>Four;[$Roll]<br />
--X|<br />
<br />
--:One| --+Value|was One ([%1%]) --<|<br />
--:Two| --+Value|was Two ([%1%]) --<|<br />
--:Three| --+Value|was Three ([%1%]) --<|<br />
--:Four| --+Value|was Four ([%1%]) --<|<br />
}}<br />
</pre><br />
<br />
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 variable as a parameter.<br />
<br />
=== Save and Load (--s and --l) ===<br />
<br />
This statement pair is used to either store (--s) or load (--l) data from persistent storage. Items stored in persistent storage remain between card rolls and between Roll20 sessions. There are two types of data that can be stored: settings and roll variables. <br />
<br />
Examples:<br />
<br />
<pre><br />
--Ssettings|GreenStyle<br />
--Srollvariables|FirstCardVars<br />
</pre><br />
<br />
In this case, the tag for the statement determines what type of item is being saved (settings or rollvariables). When saving settings, all non-default settings are written to the named setting storage value. When Roll Variables are saved, all variables that currently exist will be saved to the named storage value.<br />
<br />
Loading stored items simply requires the same command with the --l statement type:<br />
<br />
<pre><br />
--Lsettings|GreenStyle<br />
--Lrollvariables|FirstCardVars<br />
</pre><br />
<br />
When loading settings, all stored settings will be applied to the current card settings. You can override settings by changing them after the load.<br />
<br />
When loading roll variables, the saved variables will be added to (or overwrite if they have the same name) any variables on the current card. This means it is safe to create roll variables before the load statement.<br />
<br />
'''Practical Uses'''<br />
The major intended use of persistent storage is for storing card formats for use in later scripts. For example, the following script:<br />
<br />
<pre><br />
!scriptcard {{<br />
--#titlecardbackground|#22CC22<br />
--#oddrowbackground|#cceecc<br />
--#evenrowbackground|#99ee99<br />
--Ssettings|@{selected|token_name}<br />
}}<br />
</pre><br />
<br />
Would save the titlecardbackground, oddrowbackground, and evenrowbackground settings to a saved list named after the selected token's name. When creating cards for that token to run later, you could include the line:<br />
<br />
<pre><br />
--Lsettings|@{selected|token_name}<br />
</pre><br />
<br />
To load all of the settings at once. By creating these setting sets for each character, you can specify a different color scheme for each character that can then be used in cards with a single formatting line.<br />
<br />
There is a supplemental ! command added to support saved settings:<br />
<br />
<pre><br />
!sc-liststoredsettings<br />
</pre><br />
<br />
Will produce a list of all stored setting names, with buttons to list the setting values stored in each group and a button to delete groups as needed.<br />
<br />
=== Visual Effects (--v) ===<br />
<br />
The --v statement can be used to create visual effects on the tabletop. The tag portion of the statement can be either "token" or "betweentokens". The content portion of the statement contains the required parameters for the effect generation, separated by spaces. If the effect is "none", no effect will be played. If any other value that doesn't match a Roll20 effect name will result in a burst-fire effect.<br />
<br />
For "token" effects, the parameters are the token id for the token the effect happens on, followed by the effect specifier.<br />
<br />
Example:<br />
<pre><br />
--vtoken|@{selected|token_id} burst-fire<br />
</pre><br />
<br />
For "betweentoken" effects, the parameters are the source token id, the target token id, and the effect specifier.<br />
<br />
Example:<br />
<pre><br />
--vbetweentokens|@{selected|token_id} @{target|token_id} beam-magic<br />
</pre><br />
<br />
'''''Version 1.2.8+'''''<br />
<br />
An additional effect specifier, "point" is available in 1.2.8+. This specifier allows you to create a visual effect at a designated X/Y pixel coordinate. Future updates will add custom-vfx support to this option. The parameters are the X and Y coordinates and the effect descriptor. As of version 1.2.9, you can also use custom effect specifiers with Point effects:<br />
<br />
<pre><br />
--vpoint|150 200 burst-fire<br />
</pre><br />
<br />
=== Audio Effects (--a) ===<br />
<br />
'''''Requires version 1.5.2+'''''<br />
<br />
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.<br />
<br />
<pre><br />
--a|SwordHitSound<br />
</pre><br />
<br />
No external APIs are required.<br />
<br />
=== Echo to Chat (--e) ===<br />
<br />
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.<br />
<br />
Example:<br />
<pre><br />
--eThe Ghost|/em hovers around @{selected|character_name}... BOO!<br />
</pre><br />
<br />
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).<br />
<br />
'''''Whispering'''''<br />
<br />
You can use the echo statement to send a whisper, but there's a trick to it. If you execute this code here:<br />
<br />
<pre><br />
--eThe Ghost|/w ExamplePlayerName Boo.<br />
</pre><br />
<br />
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.<br />
<br />
So, in conclusion, it's best to use something like this when you're sending a whisper:<br />
<br />
<pre><br />
!script {{<br />
--#hidecard|1<br />
--&sender|The Ghost<br />
--&receiver|ExamplePlayerName<br />
--&message|Boo.<br />
--e[&sender]|/w [&receiver] [&message]<br />
--eScriptCards|/w gm **Whispered from [&sender] to [&receiver]:** [&message] <br />
}}<br />
</pre><br />
<br />
This will ensure that the message appears in your chat feed as well.<br />
<br />
=== Repeating Section Access (--R) ===<br />
<br />
ScriptCards (as of v0.0.13) supports accessing repeating section rows on a character sheet (for example: the attacks, the items, and the repeating resources) with the --R statement type. <br />
<br />
There are three basic commands you can use with --R, and they are specified by <br />
the tag used:<br />
<br />
<br />
'''''The "find" tag'''''<br />
<br />
An Rfind statement is used to search through a repeating field. Here is the general form of such a statement.<br />
<br />
<pre><br />
--Rfind|characterid;EntryName;SectionPrefix;SearchField<br />
</pre><br />
<br />
This is the most direct way to access a repeating section row. Supplying the character ID, followed by what you are looking for (Greatsword, for example), followed by the character sheet's section prefix (repeating_attack), followed by the field to check what you are searching for (atkname) will load the matching section (if found) into the script parsers memory. For example:<br />
<br />
<pre><br />
--Rfind|@{selected|character_id};Greatsword;repeating_attack;atkname<br />
</pre><br />
<br />
Will look at the character's "repeating_attack" section for an entry with an atkname value equal to "Greatsword". Similarly:<br />
<br />
<pre><br />
--Rfind|@{selected|character_id};Bite;repeating_npcaction;name<br />
</pre><br />
<br />
Will look for a "Bite" action on an NPC's action list.<br />
<br />
<br />
'''''The "first" tag'''''<br />
<br />
<pre><br />
--Rfirst|characterid;section prefix<br />
</pre><br />
<br />
This form of the --R command will look at all of the entries in the specified repeating section and load the first one into memory:<br />
<br />
<pre><br />
--Rfirst|@{selected|character_id};repeating_attack<br />
</pre><br />
<br />
Would load the character's first "repeating_attack" row into memory.<br />
<br />
<br />
'''''The "next" tag'''''<br />
<br />
<pre><br />
--Rnext|<br />
</pre><br />
<br />
No parameters are required for --Rnext, which loads the next entry in the list that was obtained with "first" into memory.<br />
<br />
<br />
'''''Section prefixes and how to use them'''''<br />
<br />
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 open [[D&D 5E by Roll20|this page]], and search for the phrase "repeating sections".<br />
<br />
<br />
'''''Additional information'''''<br />
<br />
However a row is obtained, it will be parsed to replace any attribute references (ie, @{level}) with the corresponding character attribute.<br />
<br />
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".<br />
<br />
You can reference repeating attribute data using the syntax [*R:attributename] syntax (similar to referencing standard character attributes).<br />
<br />
Here are some examples:<br />
<br />
Display the details of the "Greatsword" PC attack:<br />
<br />
<pre><br />
!script {{<br />
--Rfind|@{selected|character_id};Greatsword;repeating_attack;atkname<br />
--+Attack Name|[*R:atkname]<br />
--+Base Damage|[*R:dmgbase]<br />
}}<br />
</pre><br />
<br />
[[File:Scriptcards repeating greatsword.png|Repeating Greatsword Attack]]<br />
<br />
List all of the actions an NPC can take (just actions, not legendary, etc.)<br />
<br />
<pre><br />
!script {{<br />
--#title|NPC Actions<br />
--#leftsub|@{selected|token_name}<br />
--Rfirst|@{selected|character_id};repeating_npcaction<br />
--:DisplayLoop|<br />
--?"[*R:name]" -eq NoRepeatingAttributeLoaded|Done<br />
--+Action:|[*R:name] [*R:attack_damage] [*R:attack_damagetype]<br />
--?"[*R:attack_damage2]" -eq ""|NoSecondaryDamage<br />
--+ |[*R:attack_damage2] [*R:attack_damagetype2]<br />
--:NoSecondaryDamage|<br />
--Rnext|<br />
-->DisplayLoop| <br />
--:Done|<br />
}}<br />
</pre><br />
<br />
[[File:Scriptcards repeating npcactions.png]]<br />
<br />
In the script above, we get the "first" repeating_npcaction and display information about it. We then execute "next" and repeat until we run into "NoRepeatingAttributeLoaded".<br />
<br />
See the section named [[#Repeating Section Values|Repeating Section Values]] for more information.<br />
<br />
<br />
'''''Special debugging command: dump'''''<br />
<pre><br />
--Rdump|<br />
</pre><br />
<br />
The "dump" command will list all of the attributes ScriptCards knows about for the currently loaded repeating row to the API Console Log.<br />
<br />
=== Assign Variable to Built-In Function (--~) ===<br />
<br />
ScriptCards has the ability to run a function built into the API script and return the results to a variable. Some functions return roll variables, while others return strings. See the function table below for details. The format is:<br />
<br />
--~VariableName|function;param1;param2;param3;...<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Function Name !! Parameters !! Description<br />
|-<br />
| distance || token_A_ID;token_B_ID || Calculate the Chebyshev distance in grid units between two tokens. This is the measurement scheme D&D 4E/5E use for diagonal distance measurement<br />
|-<br />
| euclideandistance || token_A_ID;token_B_ID || Calculate the Euclidean distance between two tokens. This is essentially the Pythagorean theorem in action. Returns the result in grid units.<br />
|-<br />
| euclideanpixel || token_A_ID;token_B_ID || Calculate the Euclidean distance between two tokens and returns the result is pixels instead of grid units. <br />
|-<br />
| euclideanlong || token_A_ID;token_B_ID || 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 is calculated instead of before. More accurate over long distances. <br />
|-<br />
| manhattandistance || token_A_ID;token_B_ID || Also called "taxicabdistance" (which is an acceptable function name), this measures to how-many-over, how-many-up/down distance, disallowing diagonal movement.<br />
|-<br />
| getselected || none || 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 the first selected token, VariableName2 the second, etc.<br />
|}<br />
<br />
'''''Functions with Sub Functions'''''<br />
<br />
Most ScriptCards functions are grouped into set as sub functions. The table below lists the major functions and their sub functions.<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Function Name !! Sub Function !! Parameters !! Return Type !! Description<br />
|-<br />
| array || define || arrayname;value1;value2;... || none || Creates an array called "arrayname" and adds value1, value2, etc. to the array<br />
|-<br />
| array || sort || arrayname || none || Sorts the specified array in place in ascending order (alphabetically)<br />
|-<br />
| array || numericsort || arrayname || none || Sorts the specified array in place in ascending order (numerically) ('''''v 1.4.10+ ''''')<br />
|-<br />
| array || add || arrayname;value1;value2;... || none || Adds value1, value2, ... to the existing array "arrayname"<br />
|-<br />
| array || remove || arrayname;value1;value2;... || none || Removes value1, value2, ... from the existing array "arrayname". Resets the array index to 0.<br />
|-<br />
| array || replace || arrayname;currentvalue;newvalue || none || Replaces all occurrences of "currentvalue" in "arayname" with "newvalue"<br />
|-<br />
| array || setatindex || arrayname;index;newvalue || none || Replaces the array item at index "index" with "newvalue"<br />
|-<br />
| array || getindex || arrayname || stringVariable || Retrieves the current index in "arrayname" and stores it in the supplied string variable<br />
|-<br />
| array || setindex || arrayname;newindex || none || Sets the current index in array "arrayname" to "newindex"<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| array || removeat || arrayname;indexposition || none || Removes the item at index "indexposition" from "arrayname". Resets the current array index to 0.<br />
|-<br />
| array || indexof || arrayname;searchvalue || stringVariable || Searches the array "arrayname" for and item with the value of "searchvalue" and, if found, returns the index of the first matching value or "ArrayError" if not found<br />
|-<br />
| array || getlength || arrayname || stringVariable || Returns the number of items in array "arrayname"<br />
|-<br />
| array || pagetokens || arrayname;tokenid;(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. 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.)<br />
|-<br />
| 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.<br />
|-<br />
| array || stringify || arrayname || stringVariable || Returns all of the items in "arrayname" as a string separated by semicolons (;)<br />
|-<br />
| array || fromstring || arrayname || delimiter;string || Creates an array from "string", splitting "string" on "delimiter" to separate the items<br />
|-<br />
| array || statusmarkers|| arrayname;tokenid || none|| Creates an array (arrayname) of the active statusmarkers (sometimes called Token Markers) for the specified tokenid<br />
|-<br />
| math || angle || math;angle;tokenid;tokenid|| rollVariable || Calculates the angle between two tokens and returns the value in degrees<br />
|-<br />
| math || ceil || math;ceil;value || rollVariable || Rounds '''value''' up to the next integer, dropping any decimal portion of the number<br />
|-<br />
| math || clamp || math;clamp;value;lowerBound;upperBound || rollVariable || Returns '''value''', but restricted to the range of '''loweBound''' and '''upperBound'''.<br />
|-<br />
| math || floor || math;floor;value || rollVariable || Rounds '''value''' down, dropping any decimal portion of the number<br />
|-<br />
| math || max || math;max;valueA;valueB || rollVariable || Returns the larger of '''valueA''' vs '''valueB'''<br />
|-<br />
| math || min || math;min;valueA;valueB || rollVariable || Returns the smaller of '''valueA''' vs '''valueB'''<br />
|-<br />
| math || round || math;round;value || rollVariable || Rounds '''value''' to the nearest integer<br />
|-<br />
| string || length || string;length;stringValue || rollVariable || Returns the length of '''stringValue''' in characters<br />
|-<br />
| string || before || string;before;searchText;stringValue || stringVariable || Searches '''stringValue''' for '''searchText''' and returns the portion of '''stringValue''' prior to that text<br />
|-<br />
| string || after || string;after;searchText;stringValue || stringVariable || Searches '''stringValue''' for '''searchText''' and returns the portion of '''stringValue''' after that text<br />
|-<br />
| string || left || string;left;count;stringValue || stringVariable || Returns the leftmost '''count''' characters of '''stringValue'''<br />
|-<br />
| string || right || string;right;count;stringValue || stringVariable || Returns the rightmost '''count''' characters of '''stringValue'''<br />
|-<br />
| string || replace || string;replace;searchText;replaceText;stringValue || stringVariable || Replaces '''searchText''' in '''stringValue''' with '''replaceText''' and returns the resulting string<br />
|-<br />
| string || replaceall || string;replace;searchText;replaceText;stringValue || stringVariable || Replaces all intances of '''searchText''' in '''stringValue''' with '''replaceText''' and returns the resulting string '''''Requires 1.2.9+'''''<br />
|-<br />
| string || trim || string;trim;stringValue || stringVariable || Removes leading and trailing spaces from stringValue and returns the result. <br />
|-<br />
| string || substring || string;substring;start;count;stringValue || stringVariable || Returns '''count''' characters starting at '''start''' from '''stringValue'''<br />
|-<br />
| 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.<br />
|-<br />
| string || tolowercase || string;tolowercase;stringValue || stringVariable || Converts the passed string to lower case and assigns to the passed variable name. <br />
|-<br />
| string || touppercase || string || stringVariable || Converts the passed string to upper case and assigns to the passed variable name. <br />
|-<br />
| 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. <br />
|-<br />
| 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.<br />
|-<br />
| 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'''.<br />
|-<br />
| turnorder || clear || none || none || Clears all entries from the {{Turn Tracker}}/Initiative<br />
|-<br />
| turnorder || addtoken || tokenid;trackervalue || none || Adds the token represented by "tokenid" to the initiative tracker with an initiavie value of "trackervalue"<br />
|-<br />
| turnorder || replacetoken || tokenid;trackervalue || none || Replaces the token represented by "tokenid" in the initiative tracker with an initiavie value of "trackervalue". Will add the token if it doesn't exist in the tracker.<br />
|-<br />
| turnorder || removetoken || tokenid || none || Removes the token represented by "tokenid" from the initiative tracker if it exists<br />
|-<br />
| turnorder || addcustom || textlabel;trackervalue || none || Add a custom text entry to the {{Turn Tracker}}/Initiative named "textlabel" with an initiative value of "trackervalue"<br />
|-<br />
| system || date || getdatetime || stringVariable || Returns the date time in the active timezone (see settings) <br />
|-<br />
| system || date || getdate || stringVariable || Returns the date in the active timezone (see settings) <br />
|-<br />
| system || date || gettime || stringVariable || Returns the time in the active timezone (see settings)<br />
|-<br />
| system || dumpvariables || "rolls", "string", or "array" || none || Dumps all of the defined variables of the indicated type to the console log<br />
|-<br />
| system || findability || system;findability;charactername;abilityname || stringVariable || Returns the object ID of the ability on the indicated character or "AbilityNotFound"<br />
|-<br />
|}<br />
<br />
Examples:<br />
<br />
<pre><br />
--~HowFarAway|distance;@{selected|token_id};@{target|token_id}<br />
</pre><br />
<br />
Returns the distance (Chebyshev) between the selected and target tokens and stores it in "HowFarAway".<br />
<br />
<pre><br />
--SelectedDudes|getselected<br />
</pre><br />
<br />
If 5 tokens were selected, 6 variables would be created: SelectedDudesCount (with a value of 5), SelectedDudes1, SelectedDudes2, SelectedDudes3, SelectedDudes4, SelectedDudes5.<br />
<br />
=== Information Request (--i) ===<br />
<br />
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.<br />
<br />
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.<br />
<br />
After the user has clicked the button and responded to the requests, ScriptCards will resume processing the script from where it left off.<br />
<br />
Here is an example “i” line:<br />
<br />
<pre><br />
--IScriptCards needs additional information to continue;Click to select a target and provide information|t;MyNewTarget;Missile1Target||q;MyNameIs;What is your name?<br />
</pre><br />
<br />
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.<br />
<br />
Supported information request types are “t” for target token, and “q” for query.<br />
<br />
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).<br />
<br />
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:<br />
<br />
<pre><br />
q;UserName;What is your name?|Fred|Bob|Sally|Nancy<br />
</pre><br />
<br />
Would have a dropdown menu with four choices.<br />
<br />
=== Object Modification (--!) ===<br />
<br />
'''''Requires ScriptCards version 1.5.0+'''''<br />
<br />
Object modification support is now available in ScriptCards. As of 1.5.0, you can use the --! command to modify object properties in the game. This may help reduce the reliance on the --@ command to run other API commands to modify token/character values. The biggest benefit of this is that the changes happen as the script is processing, so the new values are available right away. <br />
<br />
The format of the command is:<br />
<pre><br />
--!<objectType>:<objectId>|setting:value|setting:value|setting:value...<br />
</pre><br />
<br />
'''objectType''' can be one of "t" for token, "c" for character, or "a" for character attribute<br />
<br />
'''objectId''' can be a token id or a character id (or "S"/"T" for the Source/Target token/char defined with --#sourcetoken and --#targettoken)<br />
<br />
'''setting''' and '''value''' pairs can be chained in a single statement separated by | to impact more than one property/attribute with a single line<br />
<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
Examples:<br />
<br />
Set the value of bar1_value for the selected token to 5:<br />
<pre> --!t:@{selected|token_id}|bar1_value:5</pre><br />
Add 1 to the bar3_value for the selected token:<br />
<br />
<pre> --!t:@{selected|token_id}|bar3_value:+=1</pre><br />
Set bar2_value to 5 and bar2_max to 10 for the selected token<br />
<br />
<pre> --!t:@{selected|token_id}|bar2_value:5|bar2_max:10</pre><br />
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:<br />
<br />
<pre> --!a:@{selected|token_id}|dndstyling:on|size:enormous|!attitude:epic</pre><br />
Adds 50 to the npc_xp attribute for the character represented by the selected token, displaying the value before and after the update:<br />
<br />
<pre><br />
!script {{<br />
--+XP|[*@{selected|token_id}:npc_xp]<br />
--!a:@{selected|token_id}|npc_xp:+=50<br />
--+XP|[*@{selected|token_id}:npc_xp]<br />
}}<br />
</pre><br />
<br />
Note that asynchronous read/update fields (bio, notes, gmnotes) are not currently supported.<br />
<br />
== Inline Formatting ==<br />
<br />
Inline formatting is processed on Direct Output lines only (--+ lines) and the following inline format markup is available:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Formatting Tags !! Description<br />
|-<br />
| [b]..[/b] || Bold the text between the markers <br />
|-<br />
| [i]..[/i] || Italicize the text between the markers <br />
|-<br />
| [u]..[/u] || Underline the text between the markers <br />
|-<br />
| [s]..[/s] || Strike-Thru the text between the markers <br />
|-<br />
| [c]..[/c] || Center alignment <br />
|-<br />
| [l]..[/l] || Left alignment <br />
|-<br />
| [r]..[/r] || Right alignment <br />
|-<br />
| [j]..[/j] || Full justification alignment <br />
|-<br />
| [#xxx]..[/#] or [#xxxxxx]..[/#] || Use a 3 or 6 digit hex code to colorize the text between the markers <br />
|-<br />
| [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, <code>[img width=128 height=128]</code> )<br />
|-<br />
| [button]caption::action[/button] || Create a button with the label "caption" that performs the action defined by "action". By default, buttons will be colored according the the buttontextcolor and buttonbackground card settings. You can optionally color individual buttons by specifying a text color and a background color as part of the [button] command (ie, [button:#ffffff:#000000] will create a button with white text on a black background. In order to set a background color, the foreground color must be specified.<br />
|-<br />
| [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. By default, buttons will be colored according the the buttontextcolor and buttonbackground card settings. You can optionally color individual buttons by specifying a text color and a background color as part of the [sheetbutton] command (ie, [sheetbutton:#ffffff:#000000] will create a button with white text on a black background. In order to set a background color, the foreground color must be specified.<br />
|-<br />
| [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. By default, buttons will be colored according the the buttontextcolor and buttonbackground card settings. You can optionally color individual buttons by specifying a text color and a background color as part of the [rbutton] command (ie, [rbutton:#ffffff:#000000] will create a button with white text on a black background. In order to set a background color, the foreground color must be specified.<br />
|-<br />
| [t] || Converted to HTML table tag. Text after the "t" will be included inside the tag (width, border, etc)<br />
|-<br />
| [/t] || Converted to HTML close table tag.<br />
|-<br />
| [tr] || Converted to HTML table row tag. Text after the "tr" will be included inside the tag<br />
|-<br />
| [/tr] || Converted to HTML close table row tag.<br />
|-<br />
| [td] || Converted to HTML table cell tag. Text after the "tr" will be included inside the tag<br />
|-<br />
| [/td] || Converted to HTML close table cell tag.<br />
|}<br />
<br />
Code Example<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Formatting Tags !! Description<br />
|-<br />
| <pre>!script {{<br />
--#title|Inline Formatting Examples<br />
--+|This text [b]is bolded[/b]<br />
--+|This text [i]is italicized[/i]<br />
--+|This text [u]is underlined[/u]<br />
--+Alignment|[l]Left[/l]<br />
--+|[c]Center[/c]<br />
--+|[r]Right[/r]<br />
--+|[j]This long bit of text is justified to fit smoothly into the display area for the card with justified wrapping.[/j]<br />
--+Colorized|[#f00]Red[/#] [#0f0]Green[/#] [#00f]Blue[/#]<br />
--+Button|[button]Do Something::DoOnClick[/button]<br />
--+Button Colors|[button:#000:#f00]Red::RedClick[/button] [button:#000:#0f0]Blue::BlueClick[/button] [button:#000:#00f]Blue::BlueClick[/button]<br />
--+Table:|<br />
--+|[t border=2 width=100%][tr][td]Cell1[/td][td]Cell2[/td][/tr][tr][td]Cell3[/td][td]Cell4[/td][/tr][/t]<br />
}}</pre> || [[File:Sc-formatting_example.png]]<br />
|}<br />
<br />
== Variables ==<br />
<br />
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. While it is possible to assign both a string and a roll variable the same name, doing so will likely result in confusion when looking at the script later, so it is not recommended.<br />
<br />
String Variables are assigned with the --& statement and are referenced using [&variableName] notation.<br />
<br />
Roll Variables are assigned with the --= statement, and the assignment value is always processed by the ScriptCards Roll Processor (resolves dice rolls, etc.)<br />
<br />
There are a handful of variables assigned automatically when a ScriptCard is executed. These are all string variables, and are:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Variable !! Value<br />
|-<br />
| SendingPlayerID || Contains the object ID of the player that sent the macro<br />
|-<br />
| SendingPlayerName || Contains the display name of the player<br />
|-<br />
| SendingPlayerColor || Contains the color code associated with the player<br />
|-<br />
| SendingPlayerSpeakingAs || The contents of the "Speaking As" dropdown window<br />
|-<br />
| SendingPlayerIsGM || Contains 1 if the player is a GM, and 0 if the player is NOT a GM<br />
|}<br />
<br />
== Arrays ==<br />
<br />
Arrays are a special type of variable, and are managed by the function (<nowiki>--~</nowiki> command). All of the array function commands follow the same pattern:<br />
<br />
<pre>--~variableName|array;subcommand;arrayname;param1;param2;param3;...</pre><br />
<br />
Not all array commands return anything to "variableName". The function table above will specify the return type of the command if any.<br />
<br />
There are a couple of different ways to create an array:<br />
<br />
The '''define''' array subcommand creates (or recreates) an array and assigns it values - one for each included parameter after the array name. For example:<br />
<br />
<pre>--~|array;define;Fruits;mango;peach;strawberry;apricot;banana;apple</pre><br />
<br />
will create an array called '''Fruits''' with 6 elements in the order listed in the command (mango, peach, etc.)<br />
<br />
You can also use two other subcommands to create arrays based on tokens:<br />
<br />
<pre>--~Count|array;pagetokens;Everybondy;@{selected|token_id}</pre><br />
<br />
and<br />
<br />
<pre>--~Count|array;selectedtokens;Selected</pre><br />
<br />
In both cases, arrays of tokens will be created, and a string variable called "Count" will be set to the number of tokens in the array. The '''pagetokens''' command returns (by default) all of the tokens on the page that contains the token passed as the parameter after the array name. You can filter the tokens that "pagetokens" includes in the array by appending an optional parameter describing the type of token you are looking for:<br />
<br />
<pre>--~Count|array;pagetokens;Everybondy;@{selected|token_id};npc</pre><br />
<br />
Will return only tokens on the page that represent characters that do not have a ''controlledby'' parameter set. The available options are "all" (default), "char", "graphic", "pc", and "npc".<br />
<br />
The '''selectedtokens''' command returns an array with all of the tokens that were selected when the script was called.<br />
<br />
You can also use an arbitrary string to create an array, specifying a delimiter with the '''fromstring''' command:<br />
<br />
<pre><br />
--&names|Fred<br />
--&names|+,Sally<br />
--&names|+,Ted<br />
--&names|+,Joyce<br />
--~|array;fromstring;,;[&names]<br />
</pre><br />
<br />
The above example builds a comma-separated string and then uses "fromstring" to create an array with 4 elements from it, specifying the comma as the delimiter.<br />
<br />
Finally, you can use the '''statusmarkers''' command to create an array with one entry for each active status marker on a specified token:<br />
<br />
<pre>--~|array;statusmarkers;Conditions;@{selected|token_id}</pre><br />
<br />
will create an array with one entry for each status active on the selected token. The array elements will be the internal name of the status (if you are using custom status marker packs, the names will be specified in the marker pack).<br />
<br />
'''Traversing Arrays'''<br />
<br />
Each array keeps track of an internal index position (starting at 0). Several commands let you manage this index:<br />
<br />
*'''getindex''' returns the current index value<br />
*'''setindex''' sets the index to the specified location in the array<br />
*'''getlength''' returns the number of elements in the array<br />
*'''indexof''' returns the index location of the specified element<br />
<br />
Other commands let you retrieve values from the array:<br />
<br />
*'''getfirst''' sets the index to 0 and returns the value at that position<br />
*'''getnext''' advances the index by 1 and returns the new current value<br />
*'''getprevious''' reduces the index by 1 and returns the new current value<br />
*'''getlast''' sets the index to the last elements in the array and returns the new current value<br />
<br />
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.<br />
<br />
'''Manipulating Array Elements'''<br />
<br />
Several array commands deal with inserting, removing, and modifying elements:<br />
<br />
*'''add''' works just like define, except that it takes an existing array and adds elements to it based on the passed parameters<br />
*'''remove''' looks for items matching each passed parameter and removes them from the indicated array if they exist<br />
*'''removeat''' allows you to specify an index location in the array and remove the element at that position<br />
*'''replace''' searches an array for a value and replaces all occurrences of it with a new value (if found)<br />
*'''sort''' sorts the elements in the array in ascending order<br />
*'''strinfigy''' returns a string variable that includes each array element separated by semicolons (;) <br />
<br />
'''Referencing Array Elements'''<br />
<br />
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.<br />
<br />
<pre><br />
!script {{<br />
--~dummy|array;pagetokens;myarray;@{selected|token_id}<br />
--~count|array;getcount;myarray<br />
--+Total:|There are [&count] graphical objects on the page<br />
--~testvar|array;getfirst;myarray<br />
--:loop|<br />
--+Value|[*[&testvar]:character_name]<br />
--~testvar|array;getnext;myarray<br />
--?[&testvar] -ne ArrayError|loop<br />
--+Loop1|Is Done!<br />
}}<br />
</pre><br />
<br />
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:<br />
<br />
<pre><br />
!script {{<br />
--~dummy|array;pagetokens;myarray;@{selected|token_id}<br />
--~count|array;getcount;myarray<br />
--+Total:|There are [&count] graphical objects on the page<br />
--%loopCounter|1;[&count]<br />
--+Value|[*[@myarray([&loopCounter])]:character_name]<br />
--%|<br />
--+Loop|Is Done!<br />
}}<br />
</pre><br />
<br />
This line : <nowiki>--+Value|[*[@myarray([&loopCounter])]:character_name]</nowiki> uses [@arrayName(index)] format (inside a [*characterid:attribute] syntax) to perform the same task as running through the loop with the index.<br />
<br />
(Note: Additional examples are on the way...)<br />
<br />
== For...Next Loops ==<br />
<br />
For...Next loops in ScriptCards are supported with the with the --% statement type. A loop is defined by starting off with:<br />
<br />
<pre><br />
--%LoopCounter|<start>;<end>;[step]<br />
</pre><br />
<br />
The start and end values are required, while the step parameter is optional. If the step is omitted, it will be assumed to be 1. A string variable named after the line tag ("LoopCounter" in the case above) will be created and will hold the current iteration value for the loop. Here is a real example:<br />
<br />
<pre><br />
--%LoopCounter|1;10;1<br />
</pre><br />
<br />
This will begin a loop identified by "LoopCounter" that will start at 1, increasing by 1 each iteration (the step) until it has completed 10 executions.<br />
<br />
The "next" statement is simply <code>--%|</code>, with no tag or parameters. This indicates to ScriptCards that it should increment the counter and go back to the beginning of the loop. Extending the example above:<br />
<br />
<pre><br />
!script {{<br />
--%LoopCounter|1;10;1<br />
--=Roll|1d20<br />
--+Loop|Counter is [&LoopCounter], roll was [$Roll]<br />
--%|<br />
}}<br />
</pre><br />
<br />
The <code>--%!|</code> sequence will break out of the loop, no matter how many iterations are remaining.<br />
<br />
The % and %! character sequences can also be used as part of a 1.2.1+ non-branching conditional to continue or break the loop:<br />
<br />
<pre><br />
--?"X[&RollInto]X" -eq "XX"|%<br />
</pre><br />
<br />
In this example, if the string variable RollInfo is empty, the loop will return to the top and continue with the next iteration, while:<br />
<br />
<pre><br />
--?"X[&RollInto]X" -eq "XX"|%!<br />
</pre><br />
<br />
Would cause the whole loop to end if the condition were true.<br />
<br />
== Referencing ==<br />
<br />
=== Roll Variables===<br />
<br />
Roll Variables can be referenced from the content portion of any line type, and from the tag portion of conditional statements. The referenced value is replaced when the line is executed.<br />
<br />
There are several modifiers that can be used to reference parts of a roll:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Modifier !! Meaning<br />
|-<br />
| No modifier || In a Direct Output Line (<nowiki>--+</nowiki>), GM Output Line (<nowiki>--*</nowiki>), or String Assignement (<nowiki>--&</nowiki>), 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<br />
|-<br />
| .Total || The end result of the roll equation. Formatting rules for "No Modifier" apply based on line type. <br />
|-<br />
| .Raw || The total value of the roll variable without any formatting, no matter what kind of line the reference is used in.<br />
|-<br />
| .Base || The cumulative result of any dice rolled in the Roll Text (Numeric modifiers are not included) <br />
|-<br />
| .Ones || The number of dice in the roll that came up as 1s <br />
|-<br />
| .Aces || The number of dice in the roll that came up as the maximum number on the die <br />
|-<br />
| .Odds || The number of dice in the roll that came up with an odd number <br />
|-<br />
| .Evens || The number of dice in the roll that came up with an even number <br />
|-<br />
| .RollText || The raw text of the roll that was use to generate the results <br />
|-<br />
| .Text || A text representation of the results of the roll, including the numbers rolled for each die <br />
|-<br />
| .tableEntryText || The text portion of the result of a table roll<br />
|-<br />
| .tableEntryImgURL || The image source portion of the result of a table roll<br />
|-<br />
| .tableEntryValue || If the tableEntryText is purely numeric, will contain the numeric value<br />
|}<br />
<br />
=== String Variables ===<br />
<br />
To reference a string variable, use the notation [&variablename]. String variables can be referenced in direct output, roll variable assignment, and string variable assignment statements.<br />
<br />
=== Character/Token Attributes ===<br />
<br />
A character or token attribute can be referenced from content portion of any type of line and is substituted when the line is executed. The general format for referencing a character attribute is [*ID:attribute]. ID can be a token ID or a character ID (these start with a dash). Additionally if you have specified a sourceToken or targetToken, you can substitute "S" or "T" for the ID (for example [*S:npc_type] will retrieve the npc_type attribute from the source token.<br />
<br />
By default, all attribute references will be pulled from the '''''character''''' object that the ID represents (either directly or by being a Token ID that represents a character).<br />
<br />
Keep in mind, that if you want to access the "max" of a character attribute (for example, the max hit points), then you cannot trust the name that your roll20 character sheet shows you when you hover your mouse over the max hit points. For example, this reference will not work: [*S:hp_max]. Instead, you need to use this reference: [*S:hp^].<br />
<br />
If your ID refers to a token, token attributes can be accessed by preceding the attribute name with "t-", for example [*S:t-aura1_radius]. Supported token attributes are:<br />
'''(NOTE: As of version 1.6.1 of ScriptCards, the below list is no longer a limitation on the token attributes you can reference. All token attributes available in Roll20 can now be accessed and the need to update the internal list as new attributes are added has been eliminated.)'''<br />
<br />
{|<br />
| t-name || t-id || t-statusmarkers || t-bar1_value<br />
|-<br />
| t-bar1_max || t-bar2_value || t-bar2_max || t-bar3_value<br />
|-<br />
| t-bar3_max || t-top || t-left || t-width<br />
|-<br />
| t-height || t-rotation || t-layer || t-aura1_radius<br />
|-<br />
| t-aura1_color || t-aura2_radius || t-aura2_color || t-aura1_square<br />
|-<br />
| t-aura2_square || t-tint_color || t-light_radius || t-light_dimradius<br />
|-<br />
| t-light_angle || t-light_losangle || t-light_multiplier || t-light_otherplayers<br />
|-<br />
| t-light_hassight || t-flipv || t-fliph || t-controlledby<br />
|-<br />
| t-_cardid || t-_pageid || t-imgsrc || t-bar1_link<br />
|-<br />
| t-bar2_link || t-bar3_link || t-represents || t-layer<br />
|-<br />
| t-isdrawing || t-name || t-gmnotes || t-showname<br />
|-<br />
| t-showplayers_name || t-showplayers_bar1 || t-showplayers_bar2 || t-showplayers_bar3<br />
|-<br />
| t-showplayers_aura1 || t-showplayers_aura2 || t-playersedit_name || t-playersedit_bar1<br />
|-<br />
| t-playersedit_bar2 || t-playersedit_bar3 || t-playersedit_aura1 || t-playersedit_aura2<br />
|-<br />
| t-lastmove || t-adv_fow_view_distance || t-has_bright_light_vision || t-has_night_vision<br />
|-<br />
| t-night_vision_distance || t-emits_bright_light || t-bright_light_distance || t-emits_low_light<br />
|-<br />
| t-low_light_distance || t-has_limit_field_of_vision || t-limit_field_of_vision_center || t-limit_field_of_vision_total<br />
|-<br />
| t-has_limit_field_of_night_vision || t-limit_field_of_night_vision_center || t-limit_field_of_night_vision_total || t-has_directional_bright_light<br />
|-<br />
| t-directional_bright_light_center || t-directional_bright_light_total || t-has_directional_dim_light || t-directional_dim_light_center<br />
|-<br />
| t-directional_dim_light_total || t-lightColor || t-tooltip || |<br />
|}<br />
<br />
'''''It is important to note that some attributes names on tokens have corresponding attribute names on characters, which represent different values. For example, [*T:id] returns the character ID, while [*T:t-id] returns the token ID.'''''<br />
<br />
=== Subroutine Parameters ===<br />
<br />
When using a gosub statement (-->) or a conditional marked as a gosub (prefixing the label with a > character), you can pass any number of parameters separated by semicolons (;) that the code in the subroutine can utilize.<br />
<br />
Subroutine parameters are numbered starting at 1, and are accessed by using the notation [%number%], so the first parameter is [%1%], the second is [%2%], etc.<br />
<br />
Parameter substitution happens on all line types, and happens prior to character attribute references or roll variable substitution.<br />
<br />
=== Campaign Attribute ===<br />
You can retrieve properties of the API's Campaign object with the [*C:attributename] syntax. For example, [*C:playerpageid] will retrieve the current player ribbon page from the Campaign object.<br />
<br />
=== Page Attributes ===<br />
If you have set the '''activepage''' parameter, you can retrieve page-related properties with the [*P:attributename] syntax, including the page's UDL parameters.<br />
<br />
=== Repeating Section Values ===<br />
<br />
You can reference repeating attribute data using the syntax [*R:attributename] syntax (similar to referencing standard character attributes). The currently active repeating row information will be used to retrieve attribute values. You can also retrieve the full attribute name for a repeating row attribute by using the [*R>attributename] notation. This is useful to pass to things like chatsetattr.<br />
<br />
See the section named [[#Repeating Section Access (--R)|Repeating Section Access]] for more information.<br />
<br />
=== Array Elements ===<br />
After an array has been declared, the elements can be referenced with [@arrayName(index)]. Array indices start at 0.<br />
<br />
=== ScriptCards Settings ===<br />
As of version 1.6.0, it is now possible to reference ScriptCards settings (set with the --# command) using the [#settingname] syntax (ie, [#title] will be replaced with the title setting at the time the reference is interpreted.<br />
<br />
== Deferred Resolution for Meta Scripts ==<br />
<br />
As of 1.2.9, ScriptCards supports a deferral character for use when calling another API script with via the <code>--@</code> statement, to defer processing of meta script references so they get processed prior to the sub-API call instead of prior to ScriptCards execution. To defer this processing for meta script ([[Tim#SelectManager|SelectManager]], [[Tim#Fetch|Fetch]]) by inserting a deferral character into the meta call. For example, if I want to have ScriptCards call [[TokenMod]] as if the token for "Quej Gr'stra" (yes, I let Roll20 name my test NPCs) I could use something like this:<br />
<br />
<pre> --@token-mod|{^& select Quej Gr'stra} _on showname</pre><br />
<br />
The <code>^</code> in between <code>{</code> and <code>&</code> will prevent SelectManager from seeing the call when the ScriptCard script is processed, but the <code>--@</code> statement will remove the deferral character so the command that will be sent by ScriptCards is:<br />
<br />
<pre>!token-mod {& select Quej Gr'stra} --on showname</pre><br />
<br />
With the deferral character removed, SelectManager will see the <code>{& select ...}</code> and do its magic.<br />
<br />
While the default deferral character is <code>^</code>, the deferral character is a setting that can be changed:<br />
<br />
<pre> --#deferralcharacter|%</pre><br />
<br />
Will make <code>%</code> the deferral character for future <code>--@</code> statements in the running script.<br />
<br />
Supported [[API:Meta_Scripts|Meta Script]] structures:<br />
* <code>{^&...}</code> - for [[Tim#SelectManager|SelectManager]]<br />
* <code>@^(...)</code> and <code>*^(...)</code> for [[Tim#Fetch|Fetch]]<br />
* <code>get^.</code> and <code>set^.</code> for [[Tim#Fetch|Muler]] (''''' v 1.4.5+ ''''')<br />
<br />
== Arrays ==<br />
<br />
Arrays are a new data type introduced in version 1.1.12 of ScriptCards, and are manipulated with associated function (--~) commands.<br />
<br />
* Arrays are a lists of strings. Items in an array cannot contain the semi-colon (;) character, as that is used to separate parameters in the function code that deals with arrays.<br />
* Arrays are accessed via the --~ script command. In some cases, the value of the tag (variable name) for array commands is not used, and can be a dummy value or simply omitted. I have omitted them in the statements below.<br />
* All commands that DO return a value return string values, even if the content is numeric.<br />
* If a command returns a value and there is some sort of reason that it isn't an array value, you will get "ArrayError" in the return value. This can happen if you reach the end of an array while stepping through it, for example, so checking for "ArrayError" can serve as the end condition for a loop.<br />
* Each array keeps track of its current index, allowing you to step forward and backwards through arrays.<br />
* Any number of arrays can be defined.<br />
* Unlike string variables and roll variables, array variables cannot (currently) be referenced directly. It is necessary to use the function (--~) syntax to manipulate arrays and get values from them as strings for use in other parts of your script.<br />
<br />
== Reentrant Scripts ==<br />
<br />
Reentrant scripts allow you to create buttons in your script code that will re-execute the script at a given label within the code. If you set the reentrant setting (<code>--#reentrant|somevalue</code>) to a non-zero value, your setting and variable information will be preserved between executions. Reentrant script can be used to present menus or choices and then continue acting.<br />
<br />
'''''Important''''': The value of the reentrant setting will be used to identify the appropriate script to resume when reentrancy is used. If more than one character can potentially run the same script at the same time, it is a good practice to include the character ID in the reentrant setting in order to maintain a separate list of variables. Something like:<br />
<br />
<pre><br />
--#reentrant|My Cool Script @{selected|character_id}<br />
</pre><br />
<br />
Reentrant buttons are created with the <code>[rbutton]Caption::ReentryLabel;Parameter[/rbutton]</code> construct. The caption will be displayed on the generated button. <code>ReentryLabel</code> is the name of a label in your script that the button will jump to when clicked, and Parameter will be passed in as a string value called <code>reentryval</code>.<br />
<br />
Example:<br />
<pre><br />
!script {{<br />
--#reentrant|testing<br />
--=Roll|1d20<br />
--+Roll|[$Roll]<br />
--&String|That was a [$Roll.Raw]!<br />
--~x|array;define;MyArray;Apple;Banana;Orange<br />
--+Try it|[rbutton]Hello!::EXEC_PC_SPELL;9[/rbutton]<br />
--X|<br />
<br />
--:EXEC_PC_SPELL|<br />
--+ReentryVal|[&reentryval]<br />
--+The value of Roll is|[$Roll]<br />
--+Value of String|[&String]<br />
--+Array|[@MyArray(0)]<br />
--X|<br />
}}<br />
</pre><br />
<br />
This script sets up some variables and then displays a button labeled "Hello!". If the user clicks the button, the script will be re-entered starting at <code>EXEC_PC_SPELL</code>, which will display the content of the variables from the original execution.<br />
<br />
'''''Note: This section needs to be expanded upon'''''<br />
<br />
==Libraries ==<br />
=== Procedure Libraries ===<br />
<br />
You can now create [[handouts]] in your game in Roll 20 with the name format "ScriptCards Library NAME", where name is a name you assign to the library. Library names are case sensitive. It is my hope that the more proficient ScriptCards scripters out there will provide procedure libraries (or procedures that can be included in libraries) for others to use to make their scripting life easier. Be they specific to a game system, or to a type of activity, I think a robust set of libraries that GMs could use to enhance their scripting capabilities would be very valuable to the community. Should such things begin to emerge, I’ll create a portion of the ScriptCards Wiki page to house them.<br />
<br />
To include one or more libraries in a script, use the +++libname+++ directive (does not need a -- line associated with it). Multiple library names can be specified by separating them with semicolons (i.e., +++General;dnd5elib;Colorize+++ would include three libraries (General, dnd5elib, and Colorize).<br />
<br />
Included libraries are separated from the main script code by the automatic inclusion of "--X|" before the first library is appended to the script, and all libraries are loaded at the end of the script before script processing takes place.<br />
<br />
Procedures and labels in libraries can be used just as if they were included in the body of your script. Note that this DOES mean that you could, technically, jump into a library with a direct branch (--^) or direct branch conditional, but I recommend using libraries to store reusable procedures.<br />
The Notes section of the library handout stores the library code, and is written just like any other ScriptCards code except:<br />
<br />
* They cannot use roll queries (?{Some Prompt:}) to get information from the user at execution time.<br />
* They cannot use @{} notation to access character and token information.<br />
<br />
Both of these limitation stem from the fact that Procedure Libraries are not processed by the chat server, which is what handles these items.<br />
<br />
Here is an example of handling damage modifications (resistance, vulnerability, and immunity) in D&D 5E with a library:<br />
<br />
<pre><br />
!script {{<br />
+++dnd5elib+++<br />
--#|Damage Modifiers Test<br />
--#targettoken|@{target|token_id}<br />
-->Lib5E_CheckDamageModifiers|ResistType;fire<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] fire damage<br />
<br />
-->Lib5E_CheckDamageModifiers|ResistType;cold<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] cold damage<br />
<br />
-->Lib5E_CheckDamageModifiers|ResistType;poison<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] poison damage<br />
<br />
-->Lib5E_CheckDamageModifiers|ResistType;acid<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] acid damage<br />
<br />
--X|<br />
}}<br />
</pre><br />
<br />
Library content (In a handout called “ScriptCards Library dnd5elib” NOTE: Paste into Notepad first and then paste into the handout in Roll20 to avoid bringing over HTML formatting from the web site):<br />
<br />
<pre><br />
--/|ScriptCards Library: dnd5elib version 0.0.1<br />
--/|Provides various utility procedures for D&D 5E games<br />
<br />
--/|Lib5E_CheckDamageModifiers handle damage resistance, vulnerability, and immunity. <br />
--/|Pass a string variable to be filled with a string to be appended to a dice roll and the damage type <br />
<br />
--:Lib5E_CheckDamageModifiers|damageVariableName;damageType<br />
--&[%1%]|<br />
--?"[*T:npc_vulnerabilities]" -inc "[%2%]"|>_Lib5E_IsVulnerable;[%1%]<br />
--?"[*T:npc_resistances]" -inc "[%2%]"|>_Lib5E_IsResistant;[%1%]<br />
--?"[*T:npc_immunities]" -inc "[%2%]"|>_Lib5E_IsImmune;[%1%]<br />
--<|<br />
<br />
--:_Lib5E_IsVulnerable| --&[%1%]| * 2 [Vulnerable] --<|<br />
--:_Lib5E_IsResistant| --&[%1%]| \ 2 [Resistant] --<|<br />
--:_Lib5E_IsImmune| --&[%1%]| * 0 [Immune] --<|<br />
</pre><br />
<br />
The idea is that the functions in the library create a string that can be appended to a roll to modify the output based on resistances, so you pass Lib5E_CheckDamageModifiers the name of the string variable you want to use and the damage type. The variable (ResistType in this case) will include either nothing, “* 2 [Vulnerable]”, “\ 2 [Resistant]”, or “* 0 [Immune]” which can be included in a roll assignment (--=) to modify the damage as appropriate. The order here might be important if an NPC is misconfigured to be both resistant and immune to the same damage type. Since immune is an absolute, having it last ensures that it will override resistant or vulnerable. A creature that is both vulnerable and resistant (again, misconfigured) will come back as resistant since that condition is checked after vulnerable.<br />
Some notes: I prefix my library labels with either “Lib5E_” or “_Lib5E_” as a clarity convention. This isn’t strictly necessary but you should be aware that if two libraries (or if your script and a library) define the same label, the last label defined will win. Since libraries are appended to the end of the script in the order you include them in the +++libname+++ directive, you can somewhat control this, but it is probably best to avoid re-declaring labels. <br />
<br />
In my case, items beginning with “Lib5E_” are intended to be called by scripts, while items beginning with “_Lib5E_” are intended to be used as subroutines by the “public” procedures. Of course, there is no reason you couldn’t call them directly.<br />
<br />
You might also note that I’ve included some library information in comment lines (--/|) at the top of the library. These are ignored by ScriptCards, and are a good way to convey requirements, parameters, usage information, etc.<br />
<br />
=== Example Libraries ===<br />
<br />
==== dnd5elib ====<br />
<br />
[https://github.com/kjaegers/ScriptCards Download the dnd5elib Library from the ScriptCards GitHub]<br />
<br />
The '''dnd5elib''' library provides a collection of utility procedures that help simplify dealing with the D&D 5E Official Sheet. Some of the procedures in this library require '''chatsetattr''' to be installed in your game. This is a growing library, and currently only has a handful of routines. They are:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Procedure Name !! Notes<br />
|-<br />
| style="white-space:nowrap" | Lib5E_CheckDamageModifiers || This procedure can be used to evaluate vulnerabilities, resistances, and invulnerabilities on an NPC. After setting the --#target| parameters, pass the Lib5E_CheckDamageModifiers procedure a variable name (no reference information) and a damage type (i.e., fire, cold, bludgeoning, etc.), and the procedure will then create a string variable with with a name equal to the first parameter that you passed into the procedure. This variable will contain a string that can be included in a roll line (--=), in order to modify the roll as appropriate. For example, '''-->Lib5E_CheckDamageModifiers|ResistType;fire''' will check the current target character's attributes for "fire" and will either return an empty string (no references), "* 0 [Immune]" if the creature is immune, "\ 2 [Resistant]" if the creature is resistant, or "* 2 [Vulnerable]" if the creature is vulnerable to fire damage.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_DeductSpellSlot || Pass in a character_id and a slot level, and the script will expend one spell slot of that level, capping the value at 0 slots remaining. For Example '''<nowiki>-->Lib5E_DeductSpellSlot|@{selected|character_id};1</nowiki>''' to deduct a first level spell slot from the selected character.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_FindResource || Used to locate a resource value on a character. Pass in a character_id, a resource name, and two variable names. The procedure will check both repeating and non-repeating resources looking for a resource whose name matches what was passed in and return three variables. The first will be a string variable named for the 3rd parameter and contains the attribute name of the resource's "name" field. The second will be a string variable named after parameter 4 and contains the resource's value field attribute name, and the third variable is a Roll Variable, also named after the 4th parameter that contains the current resource value. Example: '''<nowiki>-->Lib5E_FindResource|@{selected|character_id};Crossbow bolts;ResName;ResValue</nowiki>''' will find "Crossbow bolts" as a resource on the character and return [&ResName] which is the name of the resource attribute, [&ResValue] which is the '''name of the attribute that stores the value''' and [$ResValue] which is the current numeric value of the resource.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Global_Attack_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Attack Modifiers (repeating_tohitmod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Bless" for 1d4 active and "Being Cool" for +2 active, I will get a return string " + 1d4 [Bless] + 2 [Being Cool]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Save_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Save Modifiers (repeating_savemod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Bless" for 1d4 active and "Being Cool" for +2 active, I will get a return string " + 1d4 [Bless] + 2 [Being Cool]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Skill_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Skill Modifiers (repeating_skillmod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Guidance" for 1d4 active and "Being Cool" for +2 active, I will get a return string " + 1d4 [Guidance] + 2 [Being Cool]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_AC_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Save Modifiers (repeating_savemod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Shield of Faith" with a value of 2 active, I will get a return string " + 2 [Shield of Faith]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Damage_Modifiers || Pass a character ID and TWO string variable to set the return value. The first string will be for normal damage, and the second will be the additional damage on a crit. This procedure will look through the Global Damage Modifiers (repeating_damagemod_*) for rows that are active (checked on the character sheet) and return two strings with the dice rolls and descriptions for them (for example, if I have "Sneak Attack" with a value of 1d6 normal and 1d6 critical damage active, I will get a return string " + 1d6 [Sneak Attack]" and another string of " + 1d6 [Sneak Attack CRIT]" that can be used in a dice rolls.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_DivineSmiteDice || Used to calculate the number of dice to be rolled for a paladin's Divine Smite. Pass a target token id, a spell slot level, and a string variable to be set to the dice roll amount based on the NPC_TYPE attribute of the target token. The returned variable will contain a dice roll (like "3d8" that can be used in a --= line)<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Character_Summary || Pass a character ID to outputs a mini character sheet, including clickable buttons for attacks, actions, legendary actions, etc. Will automatically detect a PC vs NPC and output the appropriate sections.<br />
|}<br />
<br />
Due to formatting issues with the Wiki, the library code has been moved to a [https://gist.github.com/kjaegers/52f6049ddd257f0a1288aca4bbde13c5 GITHUB GIT]. Please view the GIST in raw mode and copy the text and paste it into a handout called "ScriptCards Library dnd5elib" in your Roll20 Game.<br />
<br />
== What to Know if you are Coming from PowerCards ==<br />
<br />
''Note: This section is a work in progress.''<br />
<br />
While ScriptCards and PowerCard have very similar output goals, their internals and use are quite different. The table below summarizes some of the major differences between the scripts.<br />
<br />
::{| class="wikitable"<br />
|-<br />
! PowerCards !! ScriptCards <br />
|-<br />
| With a handful of exceptions, all lines in a PowerCard macro are intended to produce a line of output on the final card. || With ScriptCards, ONLY the <code>--+</code> and <code>--*</code> statement types produces output <br />
|-<br />
| PowerCards lines begin with two dashes (<code>--</code>) followed by a unique tag name for the line, followed by a vertical bar and the content for the line. || ScriptCards lines begin with two dashes (<code>--</code>) followed by a '''statement type identifier''', which is a single character that identifies the type of line to the interpreter. This is followed by a tag (frequently optional), a vertical bar, and the parameters for the statement being executed.<br />
|-<br />
| PowerCard macros are always processed top to bottom. Lines can be hidden so they don't output anything, but there is no looping or branching (<code>--SkipTo</code> looks like a branch, but it just hides all of the lines until the referenced label. || ScriptCards scripts support true branching, including direct branching (<code>--^</code>) and procedure branching (<code>--></code>) and (<code>--<</code>). Procedures support parameters and a call stack so procedures can be nested to call other procedures.<br />
|-<br />
| All lines in a PowerCards macro need to have unique tags because PowerCards builds the card as a single JavaScript object using the tag names to store what will be displayed. This is why repeated tag names always result in the last one being shown. || ScriptCards tags do not need to be unique, and in the case of many line types are optional.<br />
|-<br />
| PowerCards conditionals result in either showing or hiding the line they are on. || ScriptCards conditionals '''''only''''' support branching as the result of the comparison. This branching can be direct (a GOTO) or procedural (a GOSUB) '''''NOTE: As of version 1.2.0, ScriptCards also supports roll/string variable assignment as a result of conditional evaluation, and later versions introduced code blocks that can be implemented as a result of a conditional'''''<br />
|-<br />
| PowerCards relies on the Roll20 [[Quantum Roll]] server and [[Inline|inline rolls]] for all dice functions || ScriptCards includes its own dice roll parser, and '''''does not support''''' [[Inline|inline rolls]]. '''''Note: As of version 1.2.3, ScriptCards will parse [[Inline|inline rolls]], inserting their final value in the place of the roll in the macro, but they are not part of or parsed by the built-in roll parser'''''<br />
|-<br />
| PowerCards RollIDs (often mistaken for variables) are assigned by analyzing the results of an inline roll, and cannot be referenced in other rolls, so you can't roll a <code>1d4</code> and then roll a <code>1d20</code> and add the <code>1d4</code> result because all of the rolls happen on the chat server before PowerCards gets the macro text. || ScriptCards supports two types of variables: <code>Roll Variables</code> and <code>String Variables</code>. Because ScriptCards uses its own roll parser and is not dependent upon the chat server, rolls and their results can be used in other rolls, math functions, output, etc.<br />
|}<br />
<br />
== Example Scripts ==<br />
<br />
'''''Note: The features available in ScriptCards have changed drastically since these examples were written. While these should still work, there are in many cases better ways to do things using language features introduces after these were constructed. Please see the [https://github.com/kjaegers/ScriptCards/tree/main/ScriptExamples Script Examples] section of the official ScriptCards GitHub repository for more updated script examples.<br />
<br />
Below are some sample scripts that utilize the various statement types in ScriptCards:<br />
<br />
=== Divine Smite ===<br />
<br />
This script will prompt the user for a spell slot level to expend on a divine smite. It will check the target's npc_type to see if it is an Undead or Fiend, which adds an additional d8 to the smite roll.<br />
<br />
[[File:ScriptCards Divine Smite.png|Divine Smite Script Output]]<br />
<br />
<pre><br />
!scriptcard {{<br />
--#title|Divine Smite<br />
--=DiceCount|?{Spell Slot Level?|1|2|3|4|5|6|7|8|9} + 1<br />
--=IsFiendOrUndead|0<br />
--?"@{target|npc_type}" -inc fiend|>IsBoosted<br />
--?"@{target|npc_type}" -inc undead|>IsBoosted<br />
--=TotalDice|[$DiceCount] + [$IsFiendOrUndead]<br />
--=SmiteRoll|[$TotalDice]d8<br />
--#emoteText|@{selected|token_name} smites @{target|token_name}<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
--+Smite|deals [$SmiteRoll] radiant damage.<br />
--X|<br />
<br />
--:IsBoosted|<br />
--=IsFiendOrUndead|1<br />
--<|<br />
}}<br />
</pre><br />
<br />
==== How It Works ====<br />
<br />
The first line sets the "title" card parameter to "Divine Smite".<br />
<br />
Line 2 Shows a query to the user asking for the spell slot level, adds one and stores the value in the "DiceCount" Roll Variable. The query/dropdown is generated by the chat server prior to the script being executed.<br />
<br />
Line 3 defaults the "IsFiendOrUndead" Roll Variable to 0.<br />
<br />
Lines 4 and 5 compare the target's "npc_type" attribute (passed by the chat server as text) to see if they include either "undead" or "fiend". If true, the IsBoosted subroutine will be called. No parameters are passed to this subroutine.<br />
<br />
Line 6 sets the "TotalDice" variable to the base (DiceCount) number plus the IsFiendOrUndead number, which will be a 0 or a 1.<br />
<br />
Line 7 calculates "SmiteRoll" by rolling a number of d8 equal to the "TotalDice" value.<br />
<br />
Lines 8-10 set the parameters for the emote, which appears above the card content. By setting the sourceToken and the targetToken, their icons will appear in the emote surrounding the text describing the action.<br />
<br />
Line 11 is the only line that actually produces output on the card. It results in "Smite deals # radiant damage".<br />
<br />
Line 12 ends the script execution, preventing the script from continuing and running the subroutines out of context.<br />
<br />
Lines 14-16 are the IsBoosted subroutine, starting with the :IsBoosted label. The IsFiendOrUndead variable is set to 1, and a return from subroutine is executed.<br />
<br />
=== Magic Missile ===<br />
<br />
This script demonstrates using a loop and calling a subroutine to fire a number of missiles determine by the spell slot level used to cast the spell.<br />
<br />
[[File:ScriptCards_MagicMissile_Fixed.png|Magic Missile Script Output]]<br />
<br />
<pre><br />
!scriptcard {{ <br />
--#title|Magic Missile<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
--=MissileCount|?{Spell Slot Level?|1|2|3|4|5|6|7|8|9} + 2<br />
--=DisplayCount|1<br />
--=MissileDamage|0<br />
--#leftsub|Slot level ?{Spell Slot Level?}<br />
--#rightsub|Ranged Attack<br />
--#emoteText|Fred uses a level ?{Spell Slot Level?} spell slot to fire [$MissileCount.Total] missiles of magical force!<br />
--:MissileLoop|<br />
-->FireMissile|<br />
--=DisplayCount|[$DisplayCount] + 1<br />
--?[$DisplayCount] -le [$MissileCount]|MissileLoop<br />
--+Total|Total damage is [$MissileDamage]<br />
--X|<br />
<br />
--:FireMissile|<br />
--=ThisMissile|1d4 + 1<br />
--=MissileDamage|[$MissileDamage] + [$ThisMissile]<br />
--+Missile|[$DisplayCount.Total] Hits for [$ThisMissile] [b]force[/b] damage<br />
--<|<br />
}}<br />
</pre><br />
<br />
==== How It Works ====<br />
<br />
Lines 1-3 set the card title, the source token and the target token. Setting these tokens causes their icons/avatars to appear in the Emote section of the card.<br />
<br />
Line 4 asks the user what spell slot level they wish to use to cast magic missile. The number of missiles fired is equal to 2 plus the spell level, and this is stored in the MissileCount variable.<br />
<br />
Line 5 stores a 1 in the DisplayCount variable. This will be used to control the loop to determine the number of missiles fired and the missile number when displaying damage rolls.<br />
<br />
Line 6 initializes MissileDamage to 0<br />
<br />
Line 7 sets the left subtitle to the text "Slot Level #", where # is the spell slot level being used.<br />
<br />
Line 8 sets the right subtitle to the text "Ranged Attack".<br />
<br />
Line 9 sets the emoteText parameter with a description of the action, including the slot level and number of missiles fired.<br />
<br />
Line 10 is a label for the missile firing loop<br />
<br />
Line 11 Calls the "FireMissile" subroutine<br />
<br />
Line 12 increases the DisplayCount variable by 1<br />
<br />
Line 13 Checks to see if there are still missles to fire (DisplayCount <= MissileCount) and if so branches to MissileLoop<br />
<br />
Line 14 Displays the total damage dealt by the spell.<br />
<br />
Line 15 stops execution of the script to prevent out of context execution of the subroutine.<br />
<br />
Lines 76-21 are the FireMissile subroutine, beginning with the FireMissile label. The 1d4+1 is rolled and assigned to "ThisMissile". The result is added to the existing MissileDamage total, and a line for the current missile is displayed with the missile number and the damage for the missile.<br />
<br />
=== Longsword Attack ===<br />
<br />
This script demonstrates a standard 5E D&D melee weapon attack, including detection of misses, fumbles, hits, and critical hits. If installed, alterbars is used to decrement the target's BAR3 value by the damage dealt.<br />
<br />
[[File:ScriptCards Longsword.png|Longsword Script Output]]<br />
<br />
<pre><br />
!scriptcard {{<br />
--#title|Longsword<br />
--#leftsub|Melee Attack<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
--#emoteText|@{selected|token_name} attacks @{target|token_name}<br />
--=TargetAC|@{target|npc_ac}<br />
--?[$TargetAC.Total] -gt 0|DoneWithAC<br />
--=TargetAC|@{target|ac}<br />
--:DoneWithAC|<br />
--=AttackRoll|1d20 + @{selected|strength_mod} [STR] + @{selected|pb} [PROF]<br />
--+Attack|@{selected|token_name} rolls [$AttackRoll] vs AC [$TargetAC].<br />
--?[$AttackRoll.Base] -eq 20|Crit<br />
--?[$AttackRoll.Base] -eq 1|Fumble<br />
--?[$AttackRoll.Total] -ge [$TargetAC.Total]|Hit<br />
--+Miss|The attack missed.<br />
--^Final|<br />
<br />
--:Fumble|<br />
--+Fumble!|The attack went horribly wrong.<br />
--^Final|<br />
<br />
--:Hit|<br />
--=Damage|1d8 + @{selected|strength_mod} [STR]<br />
--+Hit!|The attack hit @{target|token_name} for [$Damage] slashing damage.<br />
--@alter|_target|@{target|token_id} _bar|3 _amount|-[$Damage]<br />
--^Final|<br />
<br />
--:Crit|<br />
--=Damage|1d8 + @{selected|strength_mod} [STR] + 1d8 [CRIT]<br />
--+Critical Hit!|The attack hit @{target|token_name} for [$Damage] slashing damage.<br />
--@alter|_target|@{target|token_id} _bar|3 _amount|-[$Damage]<br />
<br />
--:Final|<br />
}}<br />
</pre><br />
<br />
==== How it Works ====<br />
<br />
In lines 1-5, we set the title, subtitle, and emote text along with the tokens for the emote area.<br />
<br />
Lines 6-9 allow us to determine the AC of the target. On the 5E Roll20 sheet, NPCs armor class is stored in "npc_ac", while PCs armor class is in "ac". First we grab npc_ac and if it is zero, we check AC.<br />
<br />
Line 10 rolls the attack roll, rolling 1d20 and adding the attacker's strength modifier and proficiency bonus<br />
<br />
Line 11 displays the result of the attack roll on the card<br />
<br />
Lines 12-14 determine what kind of result the attack had. If the .Base value of the roll was 20, we branch to "Crit". If it was 1, we branch to "Fumble". If the .Total value of the roll was greater than or equal to the AC that was determined in Lines 6-9, we branch to Hit.<br />
<br />
Assuming we didn't branc anywhere, the result of the attack was a miss, so we display that on line 15 and then branch to "Final"<br />
<br />
This is followed by three branch segments, :Fumble, :Hit, and :Crit. A fumble displays a text message and branches to :Final.<br />
<br />
On a hit or a crit, we roll Damage (adding additional damage dice on a crit). We display a "Hit!" or "Critical Hit!" message and then make an API call to AlterBars, passing it the token id, bar we want to modify (3 in this case), and the amount we want to modify by the Damage value.<br />
<br />
=== Party Health Status ===<br />
<br />
This example calculates the current Hit Points remaining and HP percentage for each character and creates a color-coded display with the current party status.<br />
<br />
[[File:ScriptCards Party Health.png]]<br />
<br />
<pre><br />
!scriptcard {{<br />
--#title|Party Status<br />
--#titleCardBackground|#33CC33<br />
--#oddrowbackground|#bfee90<br />
--#evenrowbackground|#90eebf<br />
-->HealthCheck|@{Quej Grastra|character_id}<br />
-->HealthCheck|@{Brim Cheuto|character_id}<br />
-->HealthCheck|@{Odug Ututees|character_id}<br />
--X|End of card Execution<br />
<br />
--:HealthCheck|<br />
--=HealthPerc|[*[%1%]:hp] / [*[%1%]:hp^] * 100 \ 1<br />
--=HealthColor|000000<br />
--?[$HealthPerc.Total] -gt 50|HealthSkip<br />
--=HealthColor|FF0000<br />
--:HealthSkip|<br />
--+[*[%1%]:character_name]|has [#[$HealthColor.RollText]][*[%1%]:hp] of [*[%1%]:hp^][/#] HP [R]([$HealthPerc.Total]%)[/R]<br />
--<|End of HealthCheck<br />
}}<br />
</pre><br />
<br />
==== How it Works ====<br />
<br />
Lines 1-4, we set the card title, and set the title background and row background colors to shades of green.<br />
<br />
Lines 5-7 make gosub calls the the "HealthCheck" subroutine, passing in the character ID of each of the named characters (these are the names of the characters in my test game)<br />
<br />
Line 8 terminates the script execution.<br />
<br />
The remaining lines of the script are the HealthCheck subroutine, which works like this:<br />
<br />
Line 10 is the subroutine label (:HealthCheck)<br />
<br />
Line 11 uses the character id passed as a parameter and combines it with character attribute lookup *(...) to retrieve the value of "hp" and "hp<nowiki>^</nowiki>" for the character. The <nowiki>^</nowiki> character is used to specify that we want the MAX value for this attribute for the second call. We divide these two numbers and multiple by 100 to get a percentage. Finally, we use integer division by 1 to round the percentage and drop the decimals. The end result gets stored in the HealthPerc roll variable.<br />
<br />
Line 12 defaults to color of the health text to black<br />
<br />
Line 13 check to see if the health percentage is greater than 50. If so, it branches to HealthSkip, preventing the script from executing line 13.<br />
<br />
Line 14 sets the color of the health text to red<br />
<br />
Line 15 is the label that will be branched to from Line 13 to skip the red coloring<br />
<br />
Line 16 again uses character attribute substitution and the passed parameter value to output a display line containing the character name, the colorized health total, and the percentage value. The percentage is right-justified.<br />
<br />
Line 17 returns from the HealthCheck subroutine.<br />
<br />
=== Expanded Magic Missile Script ===<br />
<br />
This is the expanded and enhanced version of the Magic Missile script covered in {{yt|watch?v=u50xvNzS9Zk | this video}}. It includes visual and audio effects, checking and deducting spell slots, and applying damage using either Token-Mod or Alterbars.<br />
<br />
<pre><br />
!scriptcard {{ <br />
--#title|Magic Missile<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
<br />
-->GetAndCheckSlotInformation|<br />
<br />
--=MissileCount|[$SlotLevel] + 2<br />
--=DisplayCount|1<br />
--=MissileDamage|0<br />
--#leftsub|Slot level [$SlotLevel]<br />
--#rightsub|Ranged Attack<br />
--#emoteText|@{selected|character_name} uses a level [$SlotLevel.Total] spell slot to fire [$MissileCount.Total] missiles of magical force!<br />
<br />
--:MissileLoop|<br />
-->FireMissile|<br />
--=DisplayCount|[$DisplayCount] + 1<br />
--?[$DisplayCount] -le [$MissileCount]|MissileLoop<br />
--+Total|Total damage is [$MissileDamage]<br />
-->DeductSpellSlot|<br />
--#rightsub|Level [$SlotLevel] Left: [$SlotsRemaining] <br />
-->PlayEffects|none;burst-smoke;beam-magic;spell_01<br />
-->ApplyDamageTokenmod|@{target|token_id};3;-[$MissileDamage]<br />
-->ApplyDamageAlterbars|@{target|token_id};3;-[$MissileDamage]<br />
--X|<br />
<br />
--:FireMissile|<br />
--=ThisMissile|1d4 + 1<br />
--=MissileDamage|[$MissileDamage] + [$ThisMissile]<br />
--+Missile|[$DisplayCount.Total] Hits for [$ThisMissile] [b]force[/b] damage<br />
--<|<br />
<br />
--:GetAndCheckSlotInformation|<br />
--=SlotLevel|?{Spell Slot Level?|1|2|3|4|5|6|7|8|9}<br />
--=SlotsTotal|[*S:lvl[$SlotLevel]_slots_total]<br />
--=SlotsExpended|[*S:lvl[$SlotLevel]_slots_expended]<br />
--?[$SlotsExpended.Total] -ge [$SlotsTotal.Total]|NoSlotsLeft<br />
--<|<br />
<br />
--:NoSlotsLeft|<br />
--+|[*S:character_name] has no level [$SlotLevel.Total] spell slots available.<br />
--X|<br />
<br />
--:DeductSpellSlot|<br />
--=SlotsExpended|[$SlotsExpended] + 1<br />
--@setattr|_charid [*S:character_id] _lvl[$SlotLevel]_slots_expended|[$SlotsExpended] _silent<br />
--=SlotsRemaining|[$SlotsTotal] - [$SlotsExpended]<br />
--<|<br />
<br />
--:PlayEffects|Parameters are : source effect; target effect; line effect; sound effect<br />
--vtoken|@{selected|token_id} [%1%]<br />
--vtoken|@{target|token_id} [%2%]<br />
--vbetweentokens|@{selected|token_id} @{target|token_id} [%3%]<br />
--@roll20AM|_audio,play,nomenu|[%4%]<br />
--<|<br />
<br />
--:ApplyDamageTokenmod|Parameters are tokenid;bar#;amount<br />
--@token-mod|_ignore-selected _ids [%1%] _set bar[%2%]_value|[%3%]<br />
--<|<br />
<br />
--:ApplyDamageAlterbars|<br />
--@alter|_target|[%1%] _bar|[%2%] _amount|[%3%]<br />
--<|<br />
}}<br />
</pre><br />
<br />
===Hidden Roll===<br />
<br />
A roll where only the GM sees the result of the roll.<br />
[[File:Scriptcards-hiddenroll.png|right]]<br />
<pre><br />
!script {{<br />
--#title|Stealth Check<br />
--=Roll|1d20 + @{selected|stealth}<br />
--+|@{selected|token_name} attempts to move undetected...<br />
--*GMLine|@{selected|token_name} rolled a [$Roll]<br />
}}<br />
</pre><br />
<br />
===Elsewhere===<br />
* {{fpl|10000297/ Scritpcard API Working and Sharing}}<br />
* [https://gist.github.com/dubzilla1/cba439bd1f47ecdd81d0c79a482c4a91 Pathfinder 2E heal macros]<br />
<br />
[[Category:Featured articles]]</div>5004103https://wiki.roll20.net/Script:ScriptCardsScript:ScriptCards2022-02-10T19:01:54Z<p>5004103: /* Conditional Statement (--?) */</p>
<hr />
<div>{{revdate}}<br />
== Introduction ==<br />
'''ScriptCards''' provides a script interpreter that can be used to create powerful macros that display the results of player/NPC actions, or display other information in a pleasing visual format in your game's {{Text Chat}}. The scripting language contains variables (both dice-roll (enhanced numerics) and strings) as well, conditionals, branching, subroutines with parameters, and a set of built-in functions to simplify working with Roll20 information.<br />
{{script overview<br />
|name=ScriptCards<br />
|author=[[Kurt J.]]<br />
|code=ScriptCards<br />
|version=1.4.10<br />
|lastmodified=2021-12-04}}<br />
ScriptCards is not game-system specific, and can be used with any system/sheet. Near the end of this Wiki there is a section set aside for libraries that can implement system-specific tasks, with the hope that enthusiasts playing particular systems will create and share utility functions that can be utilized by the wider community.<br />
<br />
The default display style for ScriptCards output is similar to the format used to document player and NPC abilities in Dungeons and Dragons 4th Edition, but does not have any system ties to D&D4E.<br />
<br />
Current OneClick Version : 1.4.10<br />
'''''Note:''''' '''As of 2021-12-04, ScriptCards 1.4.10 has been submitted for OneClick update. The documentation below is in the process of being updated for 1.4.10.<br />
<br />
Current Development Version : 1.5.2<br />
<br />
'''''<big>Critically Important: ScriptCards does not use/parse [[Inline|inline rolls]]. ScriptCards includes its own built-in dice roll parser to allow for the use of variables inside dice rolls. As of version 1.2.3, ScriptCards will now take inline rolls and substitute the total result value in statement strings, meaning that you can utilize inline rolls but ScriptCards will only see the result of the roll, and not parse the roll components itself.</big>'''''<br />
{{#evp:youtube|hyR7Jnq4mQM|[[Script:ScriptCards|ScriptCards]] Introduction|right|650}}<br />
* {{fpl|9752053/ ScriptCards thread}}<br />
** {{fpl|10000297/ Scritpcard API Working and Sharing}}<br />
* {{repo|kjaegers/ScriptCards/tree/main/ScriptCards_API ScriptCards_API}} - GitHub repository for source before the one-click version is updated.<br />
* {{repo|kjaegers/ScriptCards/tree/main/ScriptExamples ScriptCards Samples}} - Branch of the GitHub repo that contains sample scripts.<br />
* {{yt.be|hyR7Jnq4mQM ScriptCards Intro}} 45min, Jan 2021<br />
* {{yt.be|u50xvNzS9Zk ScriptCards Magic Missile Deep Dive}} 39min, Feb 2021<br />
__TOC__<br />
=== Is ScriptCards Related to [[PowerCards]]? ===<br />
<br />
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.<br />
<br />
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 ({{code|name}}, {{code|leftsub}}, {{code|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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
Check the '''[[#What to Know if you are Coming from PowerCards|What to Know if you are Coming from PowerCards]]'''-section for a comparison table between the two scripts.<br />
<br />
=== What is a ScriptCard Script ===<br />
<br />
A ScriptCard Script is text written into the {{Text Chat}} (either typed directly, pasted, or run via a macro) that will produce a card of information in the [[Text Chat|chat window]]. A ScriptCard Script is composed of an [[API]] command: <code><nowiki>!scriptcard {{ }}</nowiki></code> enclosing any number of lines that determine the output that will be added to the card. At it simplest, the following macro:<br />
<br />
<pre>!scriptcard {{ }}</pre><br />
<br />
Will produce just a title card that displays “ScriptCards” as the name:<br />
<br />
[[File:Scriptcard blank.png]]<br />
<br />
Of course, this is just the simplest type of macro and isn’t very useful. In order to produce useful output, we need to include lines between the <code><nowiki>{{</nowiki></code> and <code><nowiki>}}</nowiki></code> that direct the API script as to what it should do.<br />
<br />
== Structure of a ScriptCard Line ==<br />
<br />
All ScriptCard lines begin with two dashes, followed by an ''statement identifier character'' that lets ScriptCards what type of line it is. There are several of these, and they are detailed in the next section. After the line type identifier, a Tag name 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.<br />
<br />
Following the Tag is a vertical bar, and then the content of the line itself. Again, each type of line might interpret this content differently.<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Identifier !! Statement Type !! Tag !! Content !! Notes<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--/</nowiki> || Comment || unused || unused || The <code>--/</code> 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--#</nowiki> || 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").<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--+</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--=</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--&</nowiki> || Assign String 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. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--@</nowiki> || 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 (i.e., [[TokenMod|!token-mod]], or [[ChatSetAttr|!setattr]], etc.)<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--:</nowiki> || 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<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--^</nowiki> || Branch To || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--></nowiki> || Call Procedure || 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<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--<</nowiki> || 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.<br />
|- <br />
| style="white-space:nowrap" | <nowiki>--?</nowiki> || Conditional Branch || Condition to be evaluated || True Branch Label<nowiki>|</nowiki>False Branch Label || The condition will be evaluated and execution will jump to one of the two indicated branches (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 included a semicolon separated list of parameters. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--s</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--l</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--v</nowiki> || 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+'''''<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--a</nowiki> || Play Audio Track || Unused || Jukebox track name (case sensitive) || Plays an audio track by name from the Roll20 jukebox. '''''Requires v1.5.2+'''''<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--e</nowiki> || Echo to Chat || Name to send chat command as || Chat message to send || Variable substitution takes place on the tag and content.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--R</nowiki> || Retrieve Repeating Section Row information || "find", "first", or "next" || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--~</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--c</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--i</nowiki> || Information Request || User Prompt;Button Caption || InfoType;VariableName;ParameterText || See full documentation below.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--d</nowiki> || 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. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--%</nowiki> || 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. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--*</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--!</nowiki> || Object Modification || <objectType>:<objectId> || setting:value|setting:value|setting:value... || Set properties of tokens/characters or character attributes ('''''v1.5.0+ required''''')<br />
|}<br />
<br />
== ScriptCard Statement Type Details ==<br />
The sections below detail the individual statement types supported by ScriptCards<br />
<br />
=== Comment (--/) ===<br />
<br />
A --/ statement is ignored by the ScriptCards parser. You can use this type of statement to add comments and informational text to your script. <br />
<br />
Example:<br />
<pre><br />
!script {{<br />
--/|Script Name : Fireball<br />
--/|Purpose : Allow the player to cast a fireball and blow stuff up!<br />
.<br />
.<br />
.<br />
}}<br />
</pre><br />
<br />
=== Set Parameter (--#) ===<br />
<br />
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.<br />
<br />
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.<br />
<br />
'''''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.'''''<br />
<br />
Examples:<br />
<pre><br />
--#title|Magic Missile<br />
--#leftsub|Level 1 Spell<br />
--#rightsub|Force Damage<br />
</pre><br />
<br />
The three examples above set the “title”, “leftsub”, and “rightsub” values for the card to the content value for the line. <br />
<br />
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.<br />
Settings Lines do not produce output lines on the card.<br />
<br />
The following settings are available (note that parameter names are ''not'' case sensitive):<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Name !! Effect/Use !! Default Value !! Type<br />
|-<br />
| 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<br />
|-<br />
| allowplaintextinrolls || If set to a non-zero value, plain character text in rolls will be copied to the roll text || 0 || Per-Line<br />
|-<br />
| bodyFontFace || Name of the font used in the card rows || Helvetica || Global<br />
|-<br />
| bodyFontSize || Size of the text in the card rows || 14px || Global<br />
|-<br />
| bodybackgroundimage || Specify an image (content for a CSS background-image tag) for the body area || none || Global<br />
|-<br />
| buttonBackground || Background color for buttons created with [button][/button] || #1C6EA4 || Per-Line<br />
|-<br />
| buttonBackgroundImage || A CSS specifier for a background image to use for buttons (i.e. url(...);) || empty || Per-Line<br />
|-<br />
| buttonBorderColor || Border (outline) color for buttons created with [button][/button] || #999999 || Per-Line<br />
|-<br />
| buttonFontFace || Font Family specifier for captions on buttons created with [button][/button] || Tahoma || Per-Line<br />
|-<br />
| buttonFontSize|| Text size for captions on buttons created with [button][/button] || x-small || Per-Line<br />
|-<br />
| buttonTextColor|| Text color of labels on buttons created with [button][/button] || #FFFFFF || Per-Line<br />
|-<br />
| 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<br />
|-<br />
| deferralcharacter || Changes the meta script deferral sequence to the specified value || ^ || Per-Line<br />
|-<br />
| diceFontColor|| Color of the dice created with the [d4] [d6], etc. formatting markers || #1C6EA4 || Per-Line<br />
|-<br />
| dicefontsize || Size of the dice created with the [d4] [d6], etc. formatting markers || 3.0em || Per-Line<br />
|-<br />
| 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<br />
|-<br />
| disablerollprocessing || If set to a non-zero value, --= lines will not process dice rolls strings || 0 || Per-Line<br />
|-<br />
| emoteBackground || Background color of the emote area || #f5f5ba || Global<br />
|-<br />
| emoteFont || Name of the font used in emote area (above the title of the output card) || Georgia || Global<br />
|-<br />
| emoteFontColor || Color of the font in the emote area || None (Empty) || Global<br />
|-<br />
| emoteFontSize || Size of the font used in the emote area || 14px || Global<br />
|-<br />
| emoteFontWeight || Font weight for the font in the emote area || bold|| Global<br />
|-<br />
| emoteState || If set to anything other than "visible", the emote portion of the card will not be displayed || visible || Global<br />
|-<br />
| emoteText || Text to display in the emote portion of the card || None (Empty) || Global<br />
|-<br />
| emotefont || Name of the font used in the emote text area || font-family: Georgia, serif; font-weight: bold; || Global<br />
|-<br />
| evenRowBackground || Hex code for the background color for even rows || #eeeeee || Per-Line<br />
|-<br />
| evenRowFontColor || Hex code for the text color for even rows || #000000 || Per-Line<br />
|-<br />
| evenrowbackgroundimage || Specify an image (content for a CSS background-image tag) for the even card rows || none || Per-Line<br />
|-<br />
| executionlimit || Maximum number of script lines the interpreter will try to execute. This prevents "infinite loop" sandbox crashes || 40000 || Global<br />
|-<br />
| hideCard || If set to any non-default value, the entire card output will be suppressed || 0 || Global<br />
|-<br />
| 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<br />
|-<br />
| 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<br />
|-<br />
| lineheight || Vertical size of each line on the output card || normal || Per-Line<br />
|-<br />
| nominmaxhighlight || If set to anything other than "0", rolls will not display crit/fumble/mixed highlight colors. || 0 || Per-Line<br />
|-<br />
| norollhighlight || If set to anything other than "0", rolls will not be formatted (plain numbers) but will still get a tooltip with details ('''''v1.3.6b+''''') || 0 || Per-Line<br />
|-<br />
| oddRowBackground || Hex code for the background color for even rows || #d0e4f5 || Per-Line <br />
|-<br />
| oddRowFontColor || Hex code for the text color for odd rows || #000000 || Per-Line<br />
|-<br />
| oddrowbackgroundimage || Specify an image (content for a CSS background-image tag) for the odd crd rows || none || Per-Line<br />
|-<br />
| reentrant || Used to name a script for rentrant button use || 0 || Global<br />
|-<br />
| 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)0 || Global<br />
|-<br />
| rollhilightcolorboth || Background box hilight color if both a 1 and a max on the die are rolled ('''''1.4.4+''''') || #8FA4D4 || Per-Line<br />
|-<br />
| rollhilightcolorcrit || Background box hilight color if the maximum number on the die was rolled ('''''1.4.4+''''') || #88CC88 || Per-Line<br />
|-<br />
| rollhilightcolorfumble || Background box hilight color if a 1 was rolled ('''''1.4.4+''''') || #FFAAAA || Per-Line<br />
|-<br />
| rollhilightcolornormal || Background box hilight color if neither a 1 or a max on the die are rolled ('''''1.4.4+''''') || #FFFEA2 || Per-Line<br />
|- <br />
| rollhilightlineheight || Determines the height of the hilight box placed around roll results ('''''1.4.2+''''') || 1.0em || Per-Line<br />
|-<br />
| roundUp || If set to a non-default value, integer division will round up instead of down || 0 || Per-Line<br />
|-<br />
| showfromfornonwhispers || If set to a non-zero value, will include the sender on cards that aren't whispered || 0 || Global<br />
|-<br />
| 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<br />
|-<br />
| subtitleFontColor || Color of the text in the subtitle areas || #FFFFFF || Global<br />
|-<br />
| subtitleFontFace || Name of the font used on the subtitle sections || Tahoma || Global<br />
|-<br />
| subtitleFontSize || Size of the subtitle font || 13px || Global<br />
|-<br />
| subtitleSeperator || The character(s) that will be placed between leftsub and rightsub || <nowiki>&#x2666</nowiki>; || Global<br />
|-<br />
| tableBorderRadius || CSS specifier for how rounded the borders of the output card are. Use "0px;" for square borders || 6px; || Global<br />
|-<br />
| tableShadow || CSS specifier for the drop shadow under the output card || 5px 3px 3px 0px #aaa; || Global<br />
|-<br />
| tablebgcolor || Background color of the whole card. '''''Normally not visible''''' || #EEEEEE || Global<br />
|-<br />
| tableborder || Color of the border that surrounds the whole card || 2px solid #000000; || Global<br />
|-<br />
| 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<br />
|-<br />
| timezone || IANA Specifier for the local time zone, used in system/date functions || America/New_York || Per-Line<br />
|-<br />
| title || Text displayed in the title area of the card || ScriptCards || Global<br />
|-<br />
| titleCardBackground || A hex color code representing the background color of the title area. || #1c6ea4 || Global<br />
|-<br />
| titleFontColor || Color of the text on the card title || #FFFFFF || Global<br />
|-<br />
| titleFontFace || Name of the font used on the title area || Contrail One || Global<br />
|-<br />
| titleFontLineHeight || Line spacing on the title area || 1.2em || Global<br />
|-<br />
| titleFontSize || Size of the title font || 1.2em || Global<br />
|-<br />
| titlecardbackgroundimage || Specify an image (content for a CSS background-image tag) for the title card area || none || Global<br />
|-<br />
| titlecardbottomborder || Border CSS specifier for the bottom of the title card area || 2px solid #444444; || Global<br />
|-<br />
| titlecardgradient || If set to non-zero value, will place a vertical gradient on the title card area || 0 || Global<br />
|-<br />
| usehollowdice || If set to a non-zero value, the hollow/outline versions of the dice fonts will be used || 0 || Per-Line<br />
|-<br />
| whisper|| Comma separated list of who to whisper the output to. Use "gm" for [[GM|GMs]] and "self" for the sender || none || Global|}<br />
|}<br />
<br />
''Setting Lines do not produce output lines on the card''<br />
<br />
=== Direct Output (--+) ===<br />
<br />
A direct output line display 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.<br />
<br />
Examples of Direct Output lines:<br />
<pre><br />
--+Hello|World<br />
--+Attack|The monster rolls [$Attack] to hit!<br />
--+Damage|@{target|token_name} is hit for [$Damage] [#3333AA][b]frost[/b][/#] damage.<br />
</pre><br />
<br />
Direct Output lines support inline formatting, roll variable replacement, character attribute references, and procedure variables.<br />
<br />
=== GM Output (--*) ===<br />
<br />
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. <br />
<br />
Example:<br />
<pre><br />
--+PlayerLine|This line is shown on the public card<br />
--*GMLine|This line will only be shown to GMs, on a separate card.<br />
</pre><br />
<br />
=== Roll Variable Assignment (--=) ===<br />
<br />
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.<br />
<br />
'''''All components of a roll equation should be separated with spaces.'''''<br />
<br />
Examples:<br />
<pre><br />
--=MissileDamage|1d4 + 1<br />
--=Attack|1d20 + @{selected|strength_mod} [STR] + @{selected|pb} [PROF]<br />
</pre><br />
<br />
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. Text enclosed in square brackets ([]) is considered "flavor text" and will be added to the result text but does not impact the roll result.<br />
<br />
The following dice formats are supported:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Format Pattern !! Example !! Description<br />
|-<br />
| XdY || 3d8 || Simple format. Roll a Y-sided die X times<br />
|-<br />
| XdYkhZ || 2d20kh1 || Roll Y-sided die X times and keep the highest Z number of dice<br />
|-<br />
| XdYklZ || 4d6kl3 || Roll Y-sided die X times and keep the lowest Z number of dice <br />
|-<br />
| XdY>Z || 5d6>3 || Roll Y-sided die X times and count a 1 for each roll greater than Z <br />
|-<br />
| XdY<Z || 5d6<3 || Roll Y-sided die X times and count a 1 for each roll less than Z <br />
|-<br />
| 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<br />
|-<br />
| 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<br />
|-<br />
| 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)<br />
|-<br />
| 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<br />
|-<br />
| 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).<br />
|-<br />
| 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.<br />
|-<br />
| 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. ('''''v1.5.1''''')<br />
|}<br />
<br />
The following operators are supported in a roll equation:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Operator !! Operation<br />
|-<br />
| + || Addition <br />
|-<br />
| - || Subtraction <br />
|-<br />
| * || Multiplication <br />
|-<br />
| / || Division <br />
|-<br />
| \ || Integer Division (Rounds down) <br />
|-<br />
| % || Modulo (Remainder of Divison)<br />
|}<br />
<br />
Roll Variables can be accessed at any time after they have been created by using the [$VariableName] format, with the following optional modifiers:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Modifier !! Meaning<br />
|-<br />
| No modifier || In a Direct Output Line (<nowiki>--+</nowiki>) 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<br />
|-<br />
| .Total || The end result of the roll equation as an unformatted number <br />
|-<br />
| .Base || The cumulative result of any dice rolled in the Roll Text (Numeric modifiers are not included) <br />
|-<br />
| .Ones || The number of dice in the roll that came up as 1s <br />
|-<br />
| .Aces || The number of dice in the roll that came up as the maximum number on the die <br />
|-<br />
| .Odds || The number of dice in the roll that came up with an odd number <br />
|-<br />
| .Evens || The number of dice in the roll that came up with an even number <br />
|-<br />
| .RollText || The raw text of the roll that was use to generate the results <br />
|-<br />
| .Text || A text representation of the results of the roll, including the numbers rolled for each die <br />
|-<br />
| .tableEntryText || The text portion of the result of a table roll<br />
|-<br />
| .tableEntryImgURL || The image source portion of the result of a table roll<br />
|-<br />
| .tableEntryValue || Numeric value of tableEntryText (via parseInt). If a non-numeric value, will be 0<br />
|-<br />
| .Raw || The total numeric result without any formatting, even if placed somewhere formatting would normally be done. <br />
|}<br />
<br />
Examples:<br />
<pre><br />
--+Total Damage|[$MissileDamage.Total] (roll was 1d4+1)<br />
--+Base Damage|[$MissileDamage.Base] (without the +1)<br />
--=Attack|1d20 + @{selected|strength_mod} [STR] + @{selected|pb} [PROF] + [$BlessBonus] [Bless]<br />
</pre><br />
<br />
In this case, 1d4 will be rolled and stored in “BlessBonus”, which can then be used in the Attack line.<br />
<br />
'''''Mathematical Functions in Roll Expressions '''''<br />
<br />
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:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Expression !! Meaning<br />
|-<br />
| {ABS} || Absolute Value<br />
|-<br />
| {CEIL} || Ceiling value (round up to the next whole number)<br />
|-<br />
| {FLOOR} || Floor value (round down to the next whole number)<br />
|-<br />
| {ROUND} || Round value (round up if the decimal portion is greater than 0.5, otherwise round down) '''Note: As of 1.4.11, ROUND now supports :X as a suffix to round to a given number of decimal places (ie, {ROUND:2}'''<br />
|-<br />
| {NEGATE} || Multiply the value by negative one.<br />
|-<br />
| {SQRT} || Take the square root of the running value.<br />
|-<br />
| {SQUARE} || Square the running value.<br />
|-<br />
| {CUBEROOT} || Take the cube root of the running value.<br />
|-<br />
| {CUBE} || Cube the running value.<br />
|-<br />
| {SIN} || Return the SIN of running value.<br />
|-<br />
| {COS} || Return the COS of running value.<br />
|-<br />
| {TAN} || Return the TAN of running value.<br />
|-<br />
| {ASIN} || Return the ASIN of running value.<br />
|-<br />
| {ACOS} || Return the ACOS of running value.<br />
|-<br />
| {ATAN} || Return the ATAN of running value.<br />
|-<br />
| {MAX:X} || Caps the running value at X. ('''''v1.4.12''''')<br />
|-<br />
| {MIN:X} || If the running value is less than X, set the value to X. ('''''v1.4.12''''')<br />
|-<br />
| {CLAMP:X:Y} || Adjust the running value to remain between X (lower bound) and Y (upper bound) ('''''v1.4.12''''')<br />
|}<br />
<br />
Here are the syntax rules when using the above listed functions:<br />
<br />
Example 1.<br />
<br />
<pre><br />
!script {{<br />
--=output|2.9 {FLOOR}<br />
--+output|[$output]<br />
}}<br />
</pre><br />
<br />
The output from this example is "2".<br />
<br />
Example 2.<br />
<br />
<pre><br />
!script {{<br />
--=output|2.9 {FLOOR} {NEGATE} - 3<br />
--+output|[$output]<br />
}}<br />
</pre><br />
<br />
The output from this example is "-5".<br />
<br />
Basically, a function will use as its input whatever the current "running total" is.<br />
<br />
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.<br />
<br />
<br />
'''''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 <nowiki>[[ ]]</nowiki> 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.<br />
<br />
'''''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.<br />
<br />
'''Rolling on Rollable Tables'''<br />
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.<br />
<br />
''Roll Variable Lines do not produce output lines on the card.''<br />
<br />
=== String Variable Assignment (--&) ===<br />
<br />
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:<br />
<br />
<pre><br />
--&MyText|Hello<br />
</pre><br />
<br />
Here, we assign the text "Hello" to the string variable named MyText. You can also append text to a string variable by prefixing the content with a + sign:<br />
<br />
<pre><br />
--&MyText|+ World<br />
</pre><br />
<br />
If run after the statement above, MyText will now contain "Hello World".<br />
<br />
String variables can be referenced using the syntax [&variablename]<br />
<br />
=== Call API (--@) ===<br />
<br />
ScriptCards can use a Call API instruction to execute other API commands. The Tag contains the API 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 API command is executed.<br />
<br />
Examples:<br />
<pre><br />
--@eh|list<br />
--@alter|_target|@{target|token_id} _bar|3 _amount|-[$Damage]<br />
</pre><br />
<br />
In the first example above, the command <code>!eh list</code> will be executed, calling [[EncounterHelper]]. In the second, {{fpl|1216260/ AlterBars}} is called to modify a token's Bar 3 value.<br />
<br />
'''''Note:''''' When ScriptCards (or any API script) runs other API 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).<br />
<br />
See [[API:Script Index]] for more options.<br />
<br />
=== Branch Label (--:) ===<br />
<br />
A branch label defines a line in your code that can be reached by one of the branching instructions (<nowiki>--^</nowiki>, <nowiki>--></nowiki>, or <nowiki>--?</nowiki>). The Tag serves as the label name, and must be unique on the card.<br />
<br />
The vertical bar (|) separator must be present, but the content portion of the line is unused and can be treated as a comment.<br />
<br />
Examples:<br />
<pre><br />
--:MyLoop|<br />
--:CriticalHit|Will jump here if we roll a critical hit!<br />
</pre><br />
<br />
''A Branch Label line does not produce an output line on the card.''<br />
<br />
=== Branch (--^) === <br />
<br />
A Branch line 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.<br />
<br />
Examples:<br />
<pre><br />
--^MyLoop|Jumps to MyLoop<br />
--^SkipCrit|We didn't crit, so skip the Crit code<br />
</pre><br />
<br />
''A Branch line does not produce an output line on the card.''<br />
<br />
=== Call Procedure (-->) ===<br />
<br />
Similar to a branch, a Call Procedure (sometimes knows 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 (<nowiki>--<</nowiki>) 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 (;).<br />
<br />
Examples:<br />
<pre><br />
-->FixFormat|#3333FF;#999999<br />
</pre><br />
<br />
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%].<br />
<br />
=== Return (--<) ===<br />
<br />
A return instruction marks the end of a Gosub procedure. 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.<br />
<br />
Examples:<br />
<pre><br />
--<|<br />
--<|End of MySub<br />
</pre><br />
<br />
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.<br />
<br />
=== Conditional Statement (--?) ===<br />
<br />
A conditional statement contains some equation in the Tag that will be evaluated. '''''If any part of the comparison can/does contain a space, it needs to be surrounded by double quotes'''''<br />
<br />
Based on the true/false result of the evaluation, one of two execution paths will be taken. These execution paths are detailed in the content section of the statement. The "if true" path is specified first (directly after the vertical bar), and the "if false" path is specified after it, also separated by a vertical bar.<br />
<br />
Example:<br />
<pre><br />
--?[$AttackRoll.Total] -ge [$TargetAC]|Hit|Miss<br />
</pre><br />
<br />
'''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.'''<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Branch Format !! Meaning<br />
|-<br />
| Label || If just a label is specified, execution will branch to that label when the comparison is matched.<br />
|-<br />
| >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 <br />
|-<br />
| =VariableName || The roll variable "VariableName" will be assigned the value following a semicolon (for example, the code "=Roll;1d20" will assign the value "1d20" to a variable named "Roll", if the condition is true).<br />
|-<br />
| &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).<br />
|-<br />
| % or %! || The current for...next loop will perform the "next" action (%) or will break out (%!) <br />
|-<br />
| [ || Code block (see below)<br />
|}<br />
<br />
Examples:<br />
<pre><br />
--?[$AttackRoll.Base] -eq 20|CriticalHit<br />
--?[$AttackRoll.Base] -eq 1|>Fumble;@{selected|dexterity_mod}<br />
--?"@{target|npc_type}" -inc "undead"|&MonsterType;Undead|&MonsterType;Not Undead<br />
--?[$Attack.Total] >= [$ArmorClass]|>Hit|>Miss<br />
</pre><br />
<br />
In the first example, if the Base value of AttackRoll is a 20 (natural 20 on the die) execution will branch to the CriticalHit label.<br />
<br />
In the second example, 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%].<br />
<br />
The third example looks for the word "undead" in the npc_type attribute of the targeted character. If it exists in the text, the MonsterType string variable will be set to "Undead", otherwise it will be set to "Not Undead". <br />
<br />
The final example would call 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.<br />
<br />
''Text that does/may contain a space should be enclosed in double quotes.''<br />
<br />
The following comparison operators are available:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Comparator !! Meaning<br />
|-<br />
| -eq || Equal To <br />
|-<br />
| -eqi || Case insensitive Equal To <br />
|-<br />
| -ne || Not Equal To <br />
|-<br />
| -nei || Case insensitive Not Equal To <br />
|-<br />
| -gt || Greater Than <br />
|-<br />
| -ge || Greater Than or Equal To <br />
|-<br />
| -lt || Less Than <br />
|-<br />
| -le || Less Than or Equal To <br />
|-<br />
| -inc || Includes (text strings). <br />
|-<br />
| -ninc || Does Not Include (text strings). <br />
|}<br />
<br />
Multi-part conditionals are supported with -and and -or as separators. For example:<br />
<br />
<pre><br />
--?[$Attack.Total] -ge @{target|npc_ac} -and [$Attack.Base] -ne 20|HitButNotCrit<br />
</pre><br />
<br />
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):<br />
<br />
true AND false OR true<br />
<br />
Will be evaluated as true. The first two (true and false) will be false, but then false OR true will be true.<br />
<br />
Conversely:<br />
<br />
true or false and false<br />
<br />
Will be false, because the first true and false will evaluate to true, and then true and false will be false.<br />
<br />
'''CODE BLOCKS'''<br />
<br />
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.<br />
<br />
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:<br />
<br />
<pre><br />
!script {{<br />
--=Roll|1d2<br />
--+Roll|[$Roll]<br />
--?[$Roll.Total] -eq 2|[<br />
--&Value|Yep!<br />
--+|We are inside the TRUE portion of the block<br />
--]|[<br />
--&Value|Nope<br />
--+|We are inside the FALSE portion of the block<br />
--]|<br />
--+After|the blocks!<br />
--+Value|[&Value]<br />
}}<br />
</pre><br />
<br />
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 --]|. <br />
<br />
At this time, blocks cannot be nested, and can only be created as part of a conditional (--[ is not a valid statement type)<br />
<br />
''A conditional statement does not produce a line of output on the card.''<br />
<br />
=== Case Statement (--c) ===<br />
<br />
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 (:). Each match condition includes a branch label that will be used if the test value matches the item. 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:<br />
<br />
<pre><br />
!script {{<br />
--#title|Case Statement Testing<br />
--=Roll|1d4<br />
--C[$Roll.Total]|1:>One;[$Roll]|2:>Two;[$Roll]|3:>Three;[$Roll]|4:>Four;[$Roll]<br />
--X|<br />
<br />
--:One| --+Value|was One ([%1%]) --<|<br />
--:Two| --+Value|was Two ([%1%]) --<|<br />
--:Three| --+Value|was Three ([%1%]) --<|<br />
--:Four| --+Value|was Four ([%1%]) --<|<br />
}}<br />
</pre><br />
<br />
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 variable as a parameter.<br />
<br />
=== Save and Load (--s and --l) ===<br />
<br />
This statement pair is used to either store (--s) or load (--l) data from persistent storage. Items stored in persistent storage remain between card rolls and between Roll20 sessions. There are two types of data that can be stored: settings and roll variables. <br />
<br />
Examples:<br />
<br />
<pre><br />
--Ssettings|GreenStyle<br />
--Srollvariables|FirstCardVars<br />
</pre><br />
<br />
In this case, the tag for the statement determines what type of item is being saved (settings or rollvariables). When saving settings, all non-default settings are written to the named setting storage value. When Roll Variables are saved, all variables that currently exist will be saved to the named storage value.<br />
<br />
Loading stored items simply requires the same command with the --l statement type:<br />
<br />
<pre><br />
--Lsettings|GreenStyle<br />
--Lrollvariables|FirstCardVars<br />
</pre><br />
<br />
When loading settings, all stored settings will be applied to the current card settings. You can override settings by changing them after the load.<br />
<br />
When loading roll variables, the saved variables will be added to (or overwrite if they have the same name) any variables on the current card. This means it is safe to create roll variables before the load statement.<br />
<br />
'''Practical Uses'''<br />
The major intended use of persistent storage is for storing card formats for use in later scripts. For example, the following script:<br />
<br />
<pre><br />
!scriptcard {{<br />
--#titlecardbackground|#22CC22<br />
--#oddrowbackground|#cceecc<br />
--#evenrowbackground|#99ee99<br />
--Ssettings|@{selected|token_name}<br />
}}<br />
</pre><br />
<br />
Would save the titlecardbackground, oddrowbackground, and evenrowbackground settings to a saved list named after the selected token's name. When creating cards for that token to run later, you could include the line:<br />
<br />
<pre><br />
--Lsettings|@{selected|token_name}<br />
</pre><br />
<br />
To load all of the settings at once. By creating these setting sets for each character, you can specify a different color scheme for each character that can then be used in cards with a single formatting line.<br />
<br />
There is a supplemental ! command added to support saved settings:<br />
<br />
<pre><br />
!sc-liststoredsettings<br />
</pre><br />
<br />
Will produce a list of all stored setting names, with buttons to list the setting values stored in each group and a button to delete groups as needed.<br />
<br />
=== Visual Effects (--v) ===<br />
<br />
The --v statement can be used to create visual effects on the tabletop. The tag portion of the statement can be either "token" or "betweentokens". The content portion of the statement contains the required parameters for the effect generation, separated by spaces. If the effect is "none", no effect will be played. If any other value that doesn't match a Roll20 effect name will result in a burst-fire effect.<br />
<br />
For "token" effects, the parameters are the token id for the token the effect happens on, followed by the effect specifier.<br />
<br />
Example:<br />
<pre><br />
--vtoken|@{selected|token_id} burst-fire<br />
</pre><br />
<br />
For "betweentoken" effects, the parameters are the source token id, the target token id, and the effect specifier.<br />
<br />
Example:<br />
<pre><br />
--vbetweentokens|@{selected|token_id} @{target|token_id} beam-magic<br />
</pre><br />
<br />
'''''Version 1.2.8+'''''<br />
<br />
An additional effect specifier, "point" is available in 1.2.8+. This specifier allows you to create a visual effect at a designated X/Y pixel coordinate. Future updates will add custom-vfx support to this option. The parameters are the X and Y coordinates and the effect descriptor. As of version 1.2.9, you can also use custom effect specifiers with Point effects:<br />
<br />
<pre><br />
--vpoint|150 200 burst-fire<br />
</pre><br />
<br />
=== Audio Effects (--a) ===<br />
<br />
'''''Requires version 1.5.2+'''''<br />
<br />
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.<br />
<br />
<pre><br />
--a|SwordHitSound<br />
</pre><br />
<br />
No external APIs are required.<br />
<br />
=== Echo to Chat (--e) ===<br />
<br />
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.<br />
<br />
Example:<br />
<pre><br />
--eThe Ghost|/em hovers around @{selected|character_name}... BOO!<br />
</pre><br />
<br />
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).<br />
<br />
'''''Whispering'''''<br />
<br />
You can use the echo statement to send a whisper, but there's a trick to it. If you execute this code here:<br />
<br />
<pre><br />
--eThe Ghost|/w ExamplePlayerName Boo.<br />
</pre><br />
<br />
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.<br />
<br />
So, in conclusion, it's best to use something like this when you're sending a whisper:<br />
<br />
<pre><br />
!script {{<br />
--#hidecard|1<br />
--&sender|The Ghost<br />
--&receiver|ExamplePlayerName<br />
--&message|Boo.<br />
--e[&sender]|/w [&receiver] [&message]<br />
--eScriptCards|/w gm **Whispered from [&sender] to [&receiver]:** [&message] <br />
}}<br />
</pre><br />
<br />
This will ensure that the message appears in your chat feed as well.<br />
<br />
=== Repeating Section Access (--R) ===<br />
<br />
ScriptCards (as of v0.0.13) supports accessing repeating section rows on a character sheet (for example: the attacks, the items, and the repeating resources) with the --R statement type. <br />
<br />
There are three basic commands you can use with --R, and they are specified by <br />
the tag used:<br />
<br />
<br />
'''''The "find" tag'''''<br />
<br />
An Rfind statement is used to search through a repeating field. Here is the general form of such a statement.<br />
<br />
<pre><br />
--Rfind|characterid;EntryName;SectionPrefix;SearchField<br />
</pre><br />
<br />
This is the most direct way to access a repeating section row. Supplying the character ID, followed by what you are looking for (Greatsword, for example), followed by the character sheet's section prefix (repeating_attack), followed by the field to check what you are searching for (atkname) will load the matching section (if found) into the script parsers memory. For example:<br />
<br />
<pre><br />
--Rfind|@{selected|character_id};Greatsword;repeating_attack;atkname<br />
</pre><br />
<br />
Will look at the character's "repeating_attack" section for an entry with an atkname value equal to "Greatsword". Similarly:<br />
<br />
<pre><br />
--Rfind|@{selected|character_id};Bite;repeating_npcaction;name<br />
</pre><br />
<br />
Will look for a "Bite" action on an NPC's action list.<br />
<br />
<br />
'''''The "first" tag'''''<br />
<br />
<pre><br />
--Rfirst|characterid;section prefix<br />
</pre><br />
<br />
This form of the --R command will look at all of the entries in the specified repeating section and load the first one into memory:<br />
<br />
<pre><br />
--Rfirst|@{selected|character_id};repeating_attack<br />
</pre><br />
<br />
Would load the character's first "repeating_attack" row into memory.<br />
<br />
<br />
'''''The "next" tag'''''<br />
<br />
<pre><br />
--Rnext|<br />
</pre><br />
<br />
No parameters are required for --Rnext, which loads the next entry in the list that was obtained with "first" into memory.<br />
<br />
<br />
'''''Section prefixes and how to use them'''''<br />
<br />
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 open [[D&D 5E by Roll20|this page]], and search for the phrase "repeating sections".<br />
<br />
<br />
'''''Additional information'''''<br />
<br />
However a row is obtained, it will be parsed to replace any attribute references (ie, @{level}) with the corresponding character attribute.<br />
<br />
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".<br />
<br />
You can reference repeating attribute data using the syntax [*R:attributename] syntax (similar to referencing standard character attributes).<br />
<br />
Here are some examples:<br />
<br />
Display the details of the "Greatsword" PC attack:<br />
<br />
<pre><br />
!script {{<br />
--Rfind|@{selected|character_id};Greatsword;repeating_attack;atkname<br />
--+Attack Name|[*R:atkname]<br />
--+Base Damage|[*R:dmgbase]<br />
}}<br />
</pre><br />
<br />
[[File:Scriptcards repeating greatsword.png|Repeating Greatsword Attack]]<br />
<br />
List all of the actions an NPC can take (just actions, not legendary, etc.)<br />
<br />
<pre><br />
!script {{<br />
--#title|NPC Actions<br />
--#leftsub|@{selected|token_name}<br />
--Rfirst|@{selected|character_id};repeating_npcaction<br />
--:DisplayLoop|<br />
--?"[*R:name]" -eq NoRepeatingAttributeLoaded|Done<br />
--+Action:|[*R:name] [*R:attack_damage] [*R:attack_damagetype]<br />
--?"[*R:attack_damage2]" -eq ""|NoSecondaryDamage<br />
--+ |[*R:attack_damage2] [*R:attack_damagetype2]<br />
--:NoSecondaryDamage|<br />
--Rnext|<br />
-->DisplayLoop| <br />
--:Done|<br />
}}<br />
</pre><br />
<br />
[[File:Scriptcards repeating npcactions.png]]<br />
<br />
In the script above, we get the "first" repeating_npcaction and display information about it. We then execute "next" and repeat until we run into "NoRepeatingAttributeLoaded".<br />
<br />
See the section named [[#Repeating Section Values|Repeating Section Values]] for more information.<br />
<br />
<br />
'''''Special debugging command: dump'''''<br />
<pre><br />
--Rdump|<br />
</pre><br />
<br />
The "dump" command will list all of the attributes ScriptCards knows about for the currently loaded repeating row to the API Console Log.<br />
<br />
=== Assign Variable to Built-In Function (--~) ===<br />
<br />
ScriptCards has the ability to run a function built into the API script and return the results to a variable. Some functions return roll variables, while others return strings. See the function table below for details. The format is:<br />
<br />
--~VariableName|function;param1;param2;param3;...<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Function Name !! Parameters !! Description<br />
|-<br />
| distance || token_A_ID;token_B_ID || Calculate the Chebyshev distance in grid units between two tokens. This is the measurement scheme D&D 4E/5E use for diagonal distance measurement<br />
|-<br />
| euclideandistance || token_A_ID;token_B_ID || Calculate the Euclidean distance between two tokens. This is essentially the Pythagorean theorem in action. Returns the result in grid units.<br />
|-<br />
| euclideanpixel || token_A_ID;token_B_ID || Calculate the Euclidean distance between two tokens and returns the result is pixels instead of grid units. <br />
|-<br />
| euclideanlong || token_A_ID;token_B_ID || 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 is calculated instead of before. More accurate over long distances. <br />
|-<br />
| manhattandistance || token_A_ID;token_B_ID || Also called "taxicabdistance" (which is an acceptable function name), this measures to how-many-over, how-many-up/down distance, disallowing diagonal movement.<br />
|-<br />
| getselected || none || 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 the first selected token, VariableName2 the second, etc.<br />
|}<br />
<br />
'''''Functions with Sub Functions'''''<br />
<br />
Most ScriptCards functions are grouped into set as sub functions. The table below lists the major functions and their sub functions.<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Function Name !! Sub Function !! Parameters !! Return Type !! Description<br />
|-<br />
| array || define || arrayname;value1;value2;... || none || Creates an array called "arrayname" and adds value1, value2, etc. to the array<br />
|-<br />
| array || sort || arrayname || none || Sorts the specified array in place in ascending order (alphabetically)<br />
|-<br />
| array || numericsort || arrayname || none || Sorts the specified array in place in ascending order (numerically) ('''''v 1.4.10+ ''''')<br />
|-<br />
| array || add || arrayname;value1;value2;... || none || Adds value1, value2, ... to the existing array "arrayname"<br />
|-<br />
| array || remove || arrayname;value1;value2;... || none || Removes value1, value2, ... from the existing array "arrayname". Resets the array index to 0.<br />
|-<br />
| array || replace || arrayname;currentvalue;newvalue || none || Replaces all occurrences of "currentvalue" in "arayname" with "newvalue"<br />
|-<br />
| array || setatindex || arrayname;index;newvalue || none || Replaces the array item at index "index" with "newvalue"<br />
|-<br />
| array || getindex || arrayname || stringVariable || Retrieves the current index in "arrayname" and stores it in the supplied string variable<br />
|-<br />
| array || setindex || arrayname;newindex || none || Sets the current index in array "arrayname" to "newindex"<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| array || removeat || arrayname;indexposition || none || Removes the item at index "indexposition" from "arrayname". Resets the current array index to 0.<br />
|-<br />
| array || indexof || arrayname;searchvalue || stringVariable || Searches the array "arrayname" for and item with the value of "searchvalue" and, if found, returns the index of the first matching value or "ArrayError" if not found<br />
|-<br />
| array || getlength || arrayname || stringVariable || Returns the number of items in array "arrayname"<br />
|-<br />
| array || pagetokens || arrayname;tokenid;(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. 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.)<br />
|-<br />
| 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.<br />
|-<br />
| array || stringify || arrayname || stringVariable || Returns all of the items in "arrayname" as a string separated by semicolons (;)<br />
|-<br />
| array || fromstring || arrayname || delimiter;string || Creates an array from "string", splitting "string" on "delimiter" to separate the items<br />
|-<br />
| array || statusmarkers|| arrayname;tokenid || none|| Creates an array (arrayname) of the active statusmarkers (sometimes called Token Markers) for the specified tokenid<br />
|-<br />
| math || angle || math;angle;tokenid;tokenid|| rollVariable || Calculates the angle between two tokens and returns the value in degrees<br />
|-<br />
| math || ceil || math;ceil;value || rollVariable || Rounds '''value''' up to the next integer, dropping any decimal portion of the number<br />
|-<br />
| math || clamp || math;clamp;value;lowerBound;upperBound || rollVariable || Returns '''value''', but restricted to the range of '''loweBound''' and '''upperBound'''.<br />
|-<br />
| math || floor || math;floor;value || rollVariable || Rounds '''value''' down, dropping any decimal portion of the number<br />
|-<br />
| math || max || math;max;valueA;valueB || rollVariable || Returns the larger of '''valueA''' vs '''valueB'''<br />
|-<br />
| math || min || math;min;valueA;valueB || rollVariable || Returns the smaller of '''valueA''' vs '''valueB'''<br />
|-<br />
| math || round || math;round;value || rollVariable || Rounds '''value''' to the nearest integer<br />
|-<br />
| string || length || string;length;stringValue || rollVariable || Returns the length of '''stringValue''' in characters<br />
|-<br />
| string || before || string;before;searchText;stringValue || stringVariable || Searches '''stringValue''' for '''searchText''' and returns the portion of '''stringValue''' prior to that text<br />
|-<br />
| string || after || string;after;searchText;stringValue || stringVariable || Searches '''stringValue''' for '''searchText''' and returns the portion of '''stringValue''' after that text<br />
|-<br />
| string || left || string;left;count;stringValue || stringVariable || Returns the leftmost '''count''' characters of '''stringValue'''<br />
|-<br />
| string || right || string;right;count;stringValue || stringVariable || Returns the rightmost '''count''' characters of '''stringValue'''<br />
|-<br />
| string || replace || string;replace;searchText;replaceText;stringValue || stringVariable || Replaces '''searchText''' in '''stringValue''' with '''replaceText''' and returns the resulting string<br />
|-<br />
| string || replaceall || string;replace;searchText;replaceText;stringValue || stringVariable || Replaces all intances of '''searchText''' in '''stringValue''' with '''replaceText''' and returns the resulting string '''''Requires 1.2.9+'''''<br />
|-<br />
| string || trim || string;trim;stringValue || stringVariable || Removes leading and trailing spaces from stringValue and returns the result. <br />
|-<br />
| string || substring || string;substring;start;count;stringValue || stringVariable || Returns '''count''' characters starting at '''start''' from '''stringValue'''<br />
|-<br />
| 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.<br />
|-<br />
| string || tolowercase || string;tolowercase;stringValue || stringVariable || Converts the passed string to lower case and assigns to the passed variable name. <br />
|-<br />
| string || touppercase || string || stringVariable || Converts the passed string to upper case and assigns to the passed variable name. <br />
|-<br />
| 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. <br />
|-<br />
| 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.<br />
|-<br />
| 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'''.<br />
|-<br />
| turnorder || clear || none || none || Clears all entries from the {{Turn Tracker}}/Initiative<br />
|-<br />
| turnorder || addtoken || tokenid;trackervalue || none || Adds the token represented by "tokenid" to the initiative tracker with an initiavie value of "trackervalue"<br />
|-<br />
| turnorder || replacetoken || tokenid;trackervalue || none || Replaces the token represented by "tokenid" in the initiative tracker with an initiavie value of "trackervalue". Will add the token if it doesn't exist in the tracker.<br />
|-<br />
| turnorder || removetoken || tokenid || none || Removes the token represented by "tokenid" from the initiative tracker if it exists<br />
|-<br />
| turnorder || addcustom || textlabel;trackervalue || none || Add a custom text entry to the {{Turn Tracker}}/Initiative named "textlabel" with an initiative value of "trackervalue"<br />
|-<br />
| system || date || getdatetime || stringVariable || Returns the date time in the active timezone (see settings) <br />
|-<br />
| system || date || getdate || stringVariable || Returns the date in the active timezone (see settings) <br />
|-<br />
| system || date || gettime || stringVariable || Returns the time in the active timezone (see settings)<br />
|-<br />
| system || dumpvariables || "rolls", "string", or "array" || none || Dumps all of the defined variables of the indicated type to the console log<br />
|-<br />
| system || findability || system;findability;charactername;abilityname || stringVariable || Returns the object ID of the ability on the indicated character or "AbilityNotFound"<br />
|-<br />
|}<br />
<br />
Examples:<br />
<br />
<pre><br />
--~HowFarAway|distance;@{selected|token_id};@{target|token_id}<br />
</pre><br />
<br />
Returns the distance (Chebyshev) between the selected and target tokens and stores it in "HowFarAway".<br />
<br />
<pre><br />
--SelectedDudes|getselected<br />
</pre><br />
<br />
If 5 tokens were selected, 6 variables would be created: SelectedDudesCount (with a value of 5), SelectedDudes1, SelectedDudes2, SelectedDudes3, SelectedDudes4, SelectedDudes5.<br />
<br />
=== Information Request (--i) ===<br />
<br />
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.<br />
<br />
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.<br />
<br />
After the user has clicked the button and responded to the requests, ScriptCards will resume processing the script from where it left off.<br />
<br />
Here is an example “i” line:<br />
<br />
<pre><br />
--IScriptCards needs additional information to continue;Click to select a target and provide information|t;MyNewTarget;Missile1Target||q;MyNameIs;What is your name?<br />
</pre><br />
<br />
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.<br />
<br />
Supported information request types are “t” for target token, and “q” for query.<br />
<br />
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).<br />
<br />
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:<br />
<br />
<pre><br />
q;UserName;What is your name?|Fred|Bob|Sally|Nancy<br />
</pre><br />
<br />
Would have a dropdown menu with four choices.<br />
<br />
=== Object Modification (--!) ===<br />
<br />
'''''Requires ScriptCards version 1.5.0+'''''<br />
<br />
Object modification support is now available in ScriptCards. As of 1.5.0, you can use the --! command to modify object properties in the game. This may help reduce the reliance on the --@ command to run other API commands to modify token/character values. The biggest benefit of this is that the changes happen as the script is processing, so the new values are available right away. <br />
<br />
The format of the command is:<br />
<pre><br />
--!<objectType>:<objectId>|setting:value|setting:value|setting:value...<br />
</pre><br />
<br />
'''objectType''' can be one of "t" for token, "c" for character, or "a" for character attribute<br />
<br />
'''objectId''' can be a token id or a character id (or "S"/"T" for the Source/Target token/char defined with --#sourcetoken and --#targettoken)<br />
<br />
'''setting''' and '''value''' pairs can be chained in a single statement separated by | to impact more than one property/attribute with a single line<br />
<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
Examples:<br />
<br />
Set the value of bar1_value for the selected token to 5:<br />
<pre> --!t:@{selected|token_id}|bar1_value:5</pre><br />
Add 1 to the bar3_value for the selected token:<br />
<br />
<pre> --!t:@{selected|token_id}|bar3_value:+=1</pre><br />
Set bar2_value to 5 and bar2_max to 10 for the selected token<br />
<br />
<pre> --!t:@{selected|token_id}|bar2_value:5|bar2_max:10</pre><br />
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:<br />
<br />
<pre> --!a:@{selected|token_id}|dndstyling:on|size:enormous|!attitude:epic</pre><br />
Adds 50 to the npc_xp attribute for the character represented by the selected token, displaying the value before and after the update:<br />
<br />
<pre><br />
!script {{<br />
--+XP|[*@{selected|token_id}:npc_xp]<br />
--!a:@{selected|token_id}|npc_xp:+=50<br />
--+XP|[*@{selected|token_id}:npc_xp]<br />
}}<br />
</pre><br />
<br />
Note that asynchronous read/update fields (bio, notes, gmnotes) are not currently supported.<br />
<br />
== Inline Formatting ==<br />
<br />
Inline formatting is processed on Direct Output lines only (--+ lines) and the following inline format markup is available:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Formatting Tags !! Description<br />
|-<br />
| [b]..[/b] || Bold the text between the markers <br />
|-<br />
| [i]..[/i] || Italicize the text between the markers <br />
|-<br />
| [u]..[/u] || Underline the text between the markers <br />
|-<br />
| [s]..[/s] || Strike-Thru the text between the markers <br />
|-<br />
| [c]..[/c] || Center alignment <br />
|-<br />
| [l]..[/l] || Left alignment <br />
|-<br />
| [r]..[/r] || Right alignment <br />
|-<br />
| [j]..[/j] || Full justification alignment <br />
|-<br />
| [#xxx]..[/#] or [#xxxxxx]..[/#] || Use a 3 or 6 digit hex code to colorize the text between the markers <br />
|-<br />
| [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, <code>[img width=128 height=128]</code> )<br />
|-<br />
| [button]caption::action[/button] || Create a button with the label "caption" that performs the action defined by "action". By default, buttons will be colored according the the buttontextcolor and buttonbackground card settings. You can optionally color individual buttons by specifying a text color and a background color as part of the [button] command (ie, [button:#ffffff:#000000] will create a button with white text on a black background. In order to set a background color, the foreground color must be specified.<br />
|-<br />
| [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. By default, buttons will be colored according the the buttontextcolor and buttonbackground card settings. You can optionally color individual buttons by specifying a text color and a background color as part of the [sheetbutton] command (ie, [sheetbutton:#ffffff:#000000] will create a button with white text on a black background. In order to set a background color, the foreground color must be specified.<br />
|-<br />
| [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. By default, buttons will be colored according the the buttontextcolor and buttonbackground card settings. You can optionally color individual buttons by specifying a text color and a background color as part of the [rbutton] command (ie, [rbutton:#ffffff:#000000] will create a button with white text on a black background. In order to set a background color, the foreground color must be specified.<br />
|-<br />
| [t] || Converted to HTML table tag. Text after the "t" will be included inside the tag (width, border, etc)<br />
|-<br />
| [/t] || Converted to HTML close table tag.<br />
|-<br />
| [tr] || Converted to HTML table row tag. Text after the "tr" will be included inside the tag<br />
|-<br />
| [/tr] || Converted to HTML close table row tag.<br />
|-<br />
| [td] || Converted to HTML table cell tag. Text after the "tr" will be included inside the tag<br />
|-<br />
| [/td] || Converted to HTML close table cell tag.<br />
|}<br />
<br />
Code Example<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Formatting Tags !! Description<br />
|-<br />
| <pre>!script {{<br />
--#title|Inline Formatting Examples<br />
--+|This text [b]is bolded[/b]<br />
--+|This text [i]is italicized[/i]<br />
--+|This text [u]is underlined[/u]<br />
--+Alignment|[l]Left[/l]<br />
--+|[c]Center[/c]<br />
--+|[r]Right[/r]<br />
--+|[j]This long bit of text is justified to fit smoothly into the display area for the card with justified wrapping.[/j]<br />
--+Colorized|[#f00]Red[/#] [#0f0]Green[/#] [#00f]Blue[/#]<br />
--+Button|[button]Do Something::DoOnClick[/button]<br />
--+Button Colors|[button:#000:#f00]Red::RedClick[/button] [button:#000:#0f0]Blue::BlueClick[/button] [button:#000:#00f]Blue::BlueClick[/button]<br />
--+Table:|<br />
--+|[t border=2 width=100%][tr][td]Cell1[/td][td]Cell2[/td][/tr][tr][td]Cell3[/td][td]Cell4[/td][/tr][/t]<br />
}}</pre> || [[File:Sc-formatting_example.png]]<br />
|}<br />
<br />
== Variables ==<br />
<br />
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. While it is possible to assign both a string and a roll variable the same name, doing so will likely result in confusion when looking at the script later, so it is not recommended.<br />
<br />
String Variables are assigned with the --& statement and are referenced using [&variableName] notation.<br />
<br />
Roll Variables are assigned with the --= statement, and the assignment value is always processed by the ScriptCards Roll Processor (resolves dice rolls, etc.)<br />
<br />
There are a handful of variables assigned automatically when a ScriptCard is executed. These are all string variables, and are:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Variable !! Value<br />
|-<br />
| SendingPlayerID || Contains the object ID of the player that sent the macro<br />
|-<br />
| SendingPlayerName || Contains the display name of the player<br />
|-<br />
| SendingPlayerColor || Contains the color code associated with the player<br />
|-<br />
| SendingPlayerSpeakingAs || The contents of the "Speaking As" dropdown window<br />
|-<br />
| SendingPlayerIsGM || Contains 1 if the player is a GM, and 0 if the player is NOT a GM<br />
|}<br />
<br />
== Arrays ==<br />
<br />
Arrays are a special type of variable, and are managed by the function (<nowiki>--~</nowiki> command). All of the array function commands follow the same pattern:<br />
<br />
<pre>--~variableName|array;subcommand;arrayname;param1;param2;param3;...</pre><br />
<br />
Not all array commands return anything to "variableName". The function table above will specify the return type of the command if any.<br />
<br />
There are a couple of different ways to create an array:<br />
<br />
The '''define''' array subcommand creates (or recreates) an array and assigns it values - one for each included parameter after the array name. For example:<br />
<br />
<pre>--~|array;define;Fruits;mango;peach;strawberry;apricot;banana;apple</pre><br />
<br />
will create an array called '''Fruits''' with 6 elements in the order listed in the command (mango, peach, etc.)<br />
<br />
You can also use two other subcommands to create arrays based on tokens:<br />
<br />
<pre>--~Count|array;pagetokens;Everybondy;@{selected|token_id}</pre><br />
<br />
and<br />
<br />
<pre>--~Count|array;selectedtokens;Selected</pre><br />
<br />
In both cases, arrays of tokens will be created, and a string variable called "Count" will be set to the number of tokens in the array. The '''pagetokens''' command returns (by default) all of the tokens on the page that contains the token passed as the parameter after the array name. You can filter the tokens that "pagetokens" includes in the array by appending an optional parameter describing the type of token you are looking for:<br />
<br />
<pre>--~Count|array;pagetokens;Everybondy;@{selected|token_id};npc</pre><br />
<br />
Will return only tokens on the page that represent characters that do not have a ''controlledby'' parameter set. The available options are "all" (default), "char", "graphic", "pc", and "npc".<br />
<br />
The '''selectedtokens''' command returns an array with all of the tokens that were selected when the script was called.<br />
<br />
You can also use an arbitrary string to create an array, specifying a delimiter with the '''fromstring''' command:<br />
<br />
<pre><br />
--&names|Fred<br />
--&names|+,Sally<br />
--&names|+,Ted<br />
--&names|+,Joyce<br />
--~|array;fromstring;,;[&names]<br />
</pre><br />
<br />
The above example builds a comma-separated string and then uses "fromstring" to create an array with 4 elements from it, specifying the comma as the delimiter.<br />
<br />
Finally, you can use the '''statusmarkers''' command to create an array with one entry for each active status marker on a specified token:<br />
<br />
<pre>--~|array;statusmarkers;Conditions;@{selected|token_id}</pre><br />
<br />
will create an array with one entry for each status active on the selected token. The array elements will be the internal name of the status (if you are using custom status marker packs, the names will be specified in the marker pack).<br />
<br />
'''Traversing Arrays'''<br />
<br />
Each array keeps track of an internal index position (starting at 0). Several commands let you manage this index:<br />
<br />
*'''getindex''' returns the current index value<br />
*'''setindex''' sets the index to the specified location in the array<br />
*'''getlength''' returns the number of elements in the array<br />
*'''indexof''' returns the index location of the specified element<br />
<br />
Other commands let you retrieve values from the array:<br />
<br />
*'''getfirst''' sets the index to 0 and returns the value at that position<br />
*'''getnext''' advances the index by 1 and returns the new current value<br />
*'''getprevious''' reduces the index by 1 and returns the new current value<br />
*'''getlast''' sets the index to the last elements in the array and returns the new current value<br />
<br />
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.<br />
<br />
'''Manipulating Array Elements'''<br />
<br />
Several array commands deal with inserting, removing, and modifying elements:<br />
<br />
*'''add''' works just like define, except that it takes an existing array and adds elements to it based on the passed parameters<br />
*'''remove''' looks for items matching each passed parameter and removes them from the indicated array if they exist<br />
*'''removeat''' allows you to specify an index location in the array and remove the element at that position<br />
*'''replace''' searches an array for a value and replaces all occurrences of it with a new value (if found)<br />
*'''sort''' sorts the elements in the array in ascending order<br />
*'''strinfigy''' returns a string variable that includes each array element separated by semicolons (;) <br />
<br />
'''Referencing Array Elements'''<br />
<br />
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.<br />
<br />
<pre><br />
!script {{<br />
--~dummy|array;pagetokens;myarray;@{selected|token_id}<br />
--~count|array;getcount;myarray<br />
--+Total:|There are [&count] graphical objects on the page<br />
--~testvar|array;getfirst;myarray<br />
--:loop|<br />
--+Value|[*[&testvar]:character_name]<br />
--~testvar|array;getnext;myarray<br />
--?[&testvar] -ne ArrayError|loop<br />
--+Loop1|Is Done!<br />
}}<br />
</pre><br />
<br />
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:<br />
<br />
<pre><br />
!script {{<br />
--~dummy|array;pagetokens;myarray;@{selected|token_id}<br />
--~count|array;getcount;myarray<br />
--+Total:|There are [&count] graphical objects on the page<br />
--%loopCounter|1;[&count]<br />
--+Value|[*[@myarray([&loopCounter])]:character_name]<br />
--%|<br />
--+Loop|Is Done!<br />
}}<br />
</pre><br />
<br />
This line : <nowiki>--+Value|[*[@myarray([&loopCounter])]:character_name]</nowiki> uses [@arrayName(index)] format (inside a [*characterid:attribute] syntax) to perform the same task as running through the loop with the index.<br />
<br />
(Note: Additional examples are on the way...)<br />
<br />
== For...Next Loops ==<br />
<br />
For...Next loops in ScriptCards are supported with the with the --% statement type. A loop is defined by starting off with:<br />
<br />
<pre><br />
--%LoopCounter|<start>;<end>;[step]<br />
</pre><br />
<br />
The start and end values are required, while the step parameter is optional. If the step is omitted, it will be assumed to be 1. A string variable named after the line tag ("LoopCounter" in the case above) will be created and will hold the current iteration value for the loop. Here is a real example:<br />
<br />
<pre><br />
--%LoopCounter|1;10;1<br />
</pre><br />
<br />
This will begin a loop identified by "LoopCounter" that will start at 1, increasing by 1 each iteration (the step) until it has completed 10 executions.<br />
<br />
The "next" statement is simply <code>--%|</code>, with no tag or parameters. This indicates to ScriptCards that it should increment the counter and go back to the beginning of the loop. Extending the example above:<br />
<br />
<pre><br />
!script {{<br />
--%LoopCounter|1;10;1<br />
--=Roll|1d20<br />
--+Loop|Counter is [&LoopCounter], roll was [$Roll]<br />
--%|<br />
}}<br />
</pre><br />
<br />
The <code>--%!|</code> sequence will break out of the loop, no matter how many iterations are remaining.<br />
<br />
The % and %! character sequences can also be used as part of a 1.2.1+ non-branching conditional to continue or break the loop:<br />
<br />
<pre><br />
--?"X[&RollInto]X" -eq "XX"|%<br />
</pre><br />
<br />
In this example, if the string variable RollInfo is empty, the loop will return to the top and continue with the next iteration, while:<br />
<br />
<pre><br />
--?"X[&RollInto]X" -eq "XX"|%!<br />
</pre><br />
<br />
Would cause the whole loop to end if the condition were true.<br />
<br />
== Referencing ==<br />
<br />
=== Roll Variables===<br />
<br />
Roll Variables can be referenced from the content portion of any line type, and from the tag portion of conditional statements. The referenced value is replaced when the line is executed.<br />
<br />
There are several modifiers that can be used to reference parts of a roll:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Modifier !! Meaning<br />
|-<br />
| No modifier || In a Direct Output Line (<nowiki>--+</nowiki>), GM Output Line (<nowiki>--*</nowiki>), or String Assignement (<nowiki>--&</nowiki>), 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<br />
|-<br />
| .Total || The end result of the roll equation. Formatting rules for "No Modifier" apply based on line type. <br />
|-<br />
| .Raw || The total value of the roll variable without any formatting, no matter what kind of line the reference is used in.<br />
|-<br />
| .Base || The cumulative result of any dice rolled in the Roll Text (Numeric modifiers are not included) <br />
|-<br />
| .Ones || The number of dice in the roll that came up as 1s <br />
|-<br />
| .Aces || The number of dice in the roll that came up as the maximum number on the die <br />
|-<br />
| .Odds || The number of dice in the roll that came up with an odd number <br />
|-<br />
| .Evens || The number of dice in the roll that came up with an even number <br />
|-<br />
| .RollText || The raw text of the roll that was use to generate the results <br />
|-<br />
| .Text || A text representation of the results of the roll, including the numbers rolled for each die <br />
|-<br />
| .tableEntryText || The text portion of the result of a table roll<br />
|-<br />
| .tableEntryImgURL || The image source portion of the result of a table roll<br />
|-<br />
| .tableEntryValue || If the tableEntryText is purely numeric, will contain the numeric value<br />
|}<br />
<br />
=== String Variables ===<br />
<br />
To reference a string variable, use the notation [&variablename]. String variables can be referenced in direct output, roll variable assignment, and string variable assignment statements.<br />
<br />
=== Character/Token Attributes ===<br />
<br />
A character or token attribute can be referenced from content portion of any type of line and is substituted when the line is executed. The general format for referencing a character attribute is [*ID:attribute]. ID can be a token ID or a character ID (these start with a dash). Additionally if you have specified a sourceToken or targetToken, you can substitute "S" or "T" for the ID (for example [*S:npc_type] will retrieve the npc_type attribute from the source token.<br />
<br />
By default, all attribute references will be pulled from the '''''character''''' object that the ID represents (either directly or by being a Token ID that represents a character).<br />
<br />
Keep in mind, that if you want to access the "max" of a character attribute (for example, the max hit points), then you cannot trust the name that your roll20 character sheet shows you when you hover your mouse over the max hit points. For example, this reference will not work: [*S:hp_max]. Instead, you need to use this reference: [*S:hp^].<br />
<br />
If your ID refers to a token, token attributes can be accessed by preceding the attribute name with "t-", for example [*S:t-aura1_radius]. Supported token attributes are:<br />
<br />
{|<br />
| t-name || t-id || t-statusmarkers || t-bar1_value<br />
|-<br />
| t-bar1_max || t-bar2_value || t-bar2_max || t-bar3_value<br />
|-<br />
| t-bar3_max || t-top || t-left || t-width<br />
|-<br />
| t-height || t-rotation || t-layer || t-aura1_radius<br />
|-<br />
| t-aura1_color || t-aura2_radius || t-aura2_color || t-aura1_square<br />
|-<br />
| t-aura2_square || t-tint_color || t-light_radius || t-light_dimradius<br />
|-<br />
| t-light_angle || t-light_losangle || t-light_multiplier || t-light_otherplayers<br />
|-<br />
| t-light_hassight || t-flipv || t-fliph || t-controlledby<br />
|-<br />
| t-_cardid || t-_pageid || t-imgsrc || t-bar1_link<br />
|-<br />
| t-bar2_link || t-bar3_link || t-represents || t-layer<br />
|-<br />
| t-isdrawing || t-name || t-gmnotes || t-showname<br />
|-<br />
| t-showplayers_name || t-showplayers_bar1 || t-showplayers_bar2 || t-showplayers_bar3<br />
|-<br />
| t-showplayers_aura1 || t-showplayers_aura2 || t-playersedit_name || t-playersedit_bar1<br />
|-<br />
| t-playersedit_bar2 || t-playersedit_bar3 || t-playersedit_aura1 || t-playersedit_aura2<br />
|-<br />
| t-lastmove || t-adv_fow_view_distance || t-has_bright_light_vision || t-has_night_vision<br />
|-<br />
| t-night_vision_distance || t-emits_bright_light || t-bright_light_distance || t-emits_low_light<br />
|-<br />
| t-low_light_distance || t-has_limit_field_of_vision || t-limit_field_of_vision_center || t-limit_field_of_vision_total<br />
|-<br />
| t-has_limit_field_of_night_vision || t-limit_field_of_night_vision_center || t-limit_field_of_night_vision_total || t-has_directional_bright_light<br />
|-<br />
| t-directional_bright_light_center || t-directional_bright_light_total || t-has_directional_dim_light || t-directional_dim_light_center<br />
|-<br />
| t-directional_dim_light_total || t-lightColor || || |<br />
|}<br />
<br />
'''''It is important to note that some attributes names on tokens have corresponding attribute names on characters, which represent different values. For example, [*T:id] returns the character ID, while [*T:t-id] returns the token ID.'''''<br />
<br />
=== Subroutine Parameters ===<br />
<br />
When using a gosub statement (-->) or a conditional marked as a gosub (prefixing the label with a > character), you can pass any number of parameters separated by semicolons (;) that the code in the subroutine can utilize.<br />
<br />
Subroutine parameters are numbered starting at 1, and are accessed by using the notation [%number%], so the first parameter is [%1%], the second is [%2%], etc.<br />
<br />
Parameter substitution happens on all line types, and happens prior to character attribute references or roll variable substitution.<br />
<br />
=== Campaign Attribute ===<br />
You can retrieve properties of the API's Campaign object with the [*C:attributename] syntax. For example, [*C:playerpageid] will retrieve the current player ribbon page from the Campaign object.<br />
<br />
=== Page Attributes ===<br />
If you have set the '''activepage''' parameter, you can retrieve page-related properties with the [*P:attributename] syntax, including the page's UDL parameters.<br />
<br />
=== Repeating Section Values ===<br />
<br />
You can reference repeating attribute data using the syntax [*R:attributename] syntax (similar to referencing standard character attributes). The currently active repeating row information will be used to retrieve attribute values. You can also retrieve the full attribute name for a repeating row attribute by using the [*R>attributename] notation. This is useful to pass to things like chatsetattr.<br />
<br />
See the section named [[#Repeating Section Access (--R)|Repeating Section Access]] for more information.<br />
<br />
=== Array Elements ===<br />
After an array has been declared, the elements can be referenced with [@arrayName(index)]. Array indices start at 0.<br />
<br />
== Deferred Resolution for Meta Scripts ==<br />
<br />
As of 1.2.9, ScriptCards supports a deferral character for use when calling another API script with via the <code>--@</code> statement, to defer processing of meta script references so they get processed prior to the sub-API call instead of prior to ScriptCards execution. To defer this processing for meta script ([[Tim#SelectManager|SelectManager]], [[Tim#Fetch|Fetch]]) by inserting a deferral character into the meta call. For example, if I want to have ScriptCards call [[TokenMod]] as if the token for "Quej Gr'stra" (yes, I let Roll20 name my test NPCs) I could use something like this:<br />
<br />
<pre> --@token-mod|{^& select Quej Gr'stra} _on showname</pre><br />
<br />
The <code>^</code> in between <code>{</code> and <code>&</code> will prevent SelectManager from seeing the call when the ScriptCard script is processed, but the <code>--@</code> statement will remove the deferral character so the command that will be sent by ScriptCards is:<br />
<br />
<pre>!token-mod {& select Quej Gr'stra} --on showname</pre><br />
<br />
With the deferral character removed, SelectManager will see the <code>{& select ...}</code> and do its magic.<br />
<br />
While the default deferral character is <code>^</code>, the deferral character is a setting that can be changed:<br />
<br />
<pre> --#deferralcharacter|%</pre><br />
<br />
Will make <code>%</code> the deferral character for future <code>--@</code> statements in the running script.<br />
<br />
Supported [[API:Meta_Scripts|Meta Script]] structures:<br />
* <code>{^&...}</code> - for [[Tim#SelectManager|SelectManager]]<br />
* <code>@^(...)</code> and <code>*^(...)</code> for [[Tim#Fetch|Fetch]]<br />
* <code>get^.</code> and <code>set^.</code> for [[Tim#Fetch|Muler]] (''''' v 1.4.5+ ''''')<br />
<br />
== Arrays ==<br />
<br />
Arrays are a new data type introduced in version 1.1.12 of ScriptCards, and are manipulated with associated function (--~) commands.<br />
<br />
* Arrays are a lists of strings. Items in an array cannot contain the semi-colon (;) character, as that is used to separate parameters in the function code that deals with arrays.<br />
* Arrays are accessed via the --~ script command. In some cases, the value of the tag (variable name) for array commands is not used, and can be a dummy value or simply omitted. I have omitted them in the statements below.<br />
* All commands that DO return a value return string values, even if the content is numeric.<br />
* If a command returns a value and there is some sort of reason that it isn't an array value, you will get "ArrayError" in the return value. This can happen if you reach the end of an array while stepping through it, for example, so checking for "ArrayError" can serve as the end condition for a loop.<br />
* Each array keeps track of its current index, allowing you to step forward and backwards through arrays.<br />
* Any number of arrays can be defined.<br />
* Unlike string variables and roll variables, array variables cannot (currently) be referenced directly. It is necessary to use the function (--~) syntax to manipulate arrays and get values from them as strings for use in other parts of your script.<br />
<br />
== Reentrant Scripts ==<br />
<br />
Reentrant scripts allow you to create buttons in your script code that will re-execute the script at a given label within the code. If you set the reentrant setting (<code>--#reentrant|somevalue</code>) to a non-zero value, your setting and variable information will be preserved between executions. Reentrant script can be used to present menus or choices and then continue acting.<br />
<br />
'''''Important''''': The value of the reentrant setting will be used to identify the appropriate script to resume when reentrancy is used. If more than one character can potentially run the same script at the same time, it is a good practice to include the character ID in the reentrant setting in order to maintain a separate list of variables. Something like:<br />
<br />
<pre><br />
--#reentrant|My Cool Script @{selected|character_id}<br />
</pre><br />
<br />
Reentrant buttons are created with the <code>[rbutton]Caption::ReentryLabel;Parameter[/rbutton]</code> construct. The caption will be displayed on the generated button. <code>ReentryLabel</code> is the name of a label in your script that the button will jump to when clicked, and Parameter will be passed in as a string value called <code>reentryval</code>.<br />
<br />
Example:<br />
<pre><br />
!script {{<br />
--#reentrant|testing<br />
--=Roll|1d20<br />
--+Roll|[$Roll]<br />
--&String|That was a [$Roll.Raw]!<br />
--~x|array;define;MyArray;Apple;Banana;Orange<br />
--+Try it|[rbutton]Hello!::EXEC_PC_SPELL;9[/rbutton]<br />
--X|<br />
<br />
--:EXEC_PC_SPELL|<br />
--+ReentryVal|[&reentryval]<br />
--+The value of Roll is|[$Roll]<br />
--+Value of String|[&String]<br />
--+Array|[@MyArray(0)]<br />
--X|<br />
}}<br />
</pre><br />
<br />
This script sets up some variables and then displays a button labeled "Hello!". If the user clicks the button, the script will be re-entered starting at <code>EXEC_PC_SPELL</code>, which will display the content of the variables from the original execution.<br />
<br />
'''''Note: This section needs to be expanded upon'''''<br />
<br />
==Libraries ==<br />
=== Procedure Libraries ===<br />
<br />
You can now create [[handouts]] in your game in Roll 20 with the name format "ScriptCards Library NAME", where name is a name you assign to the library. Library names are case sensitive. It is my hope that the more proficient ScriptCards scripters out there will provide procedure libraries (or procedures that can be included in libraries) for others to use to make their scripting life easier. Be they specific to a game system, or to a type of activity, I think a robust set of libraries that GMs could use to enhance their scripting capabilities would be very valuable to the community. Should such things begin to emerge, I’ll create a portion of the ScriptCards Wiki page to house them.<br />
<br />
To include one or more libraries in a script, use the +++libname+++ directive (does not need a -- line associated with it). Multiple library names can be specified by separating them with semicolons (i.e., +++General;dnd5elib;Colorize+++ would include three libraries (General, dnd5elib, and Colorize).<br />
<br />
Included libraries are separated from the main script code by the automatic inclusion of "--X|" before the first library is appended to the script, and all libraries are loaded at the end of the script before script processing takes place.<br />
<br />
Procedures and labels in libraries can be used just as if they were included in the body of your script. Note that this DOES mean that you could, technically, jump into a library with a direct branch (--^) or direct branch conditional, but I recommend using libraries to store reusable procedures.<br />
The Notes section of the library handout stores the library code, and is written just like any other ScriptCards code except:<br />
<br />
* They cannot use roll queries (?{Some Prompt:}) to get information from the user at execution time.<br />
* They cannot use @{} notation to access character and token information.<br />
<br />
Both of these limitation stem from the fact that Procedure Libraries are not processed by the chat server, which is what handles these items.<br />
<br />
Here is an example of handling damage modifications (resistance, vulnerability, and immunity) in D&D 5E with a library:<br />
<br />
<pre><br />
!script {{<br />
+++dnd5elib+++<br />
--#|Damage Modifiers Test<br />
--#targettoken|@{target|token_id}<br />
-->Lib5E_CheckDamageModifiers|ResistType;fire<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] fire damage<br />
<br />
-->Lib5E_CheckDamageModifiers|ResistType;cold<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] cold damage<br />
<br />
-->Lib5E_CheckDamageModifiers|ResistType;poison<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] poison damage<br />
<br />
-->Lib5E_CheckDamageModifiers|ResistType;acid<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] acid damage<br />
<br />
--X|<br />
}}<br />
</pre><br />
<br />
Library content (In a handout called “ScriptCards Library dnd5elib” NOTE: Paste into Notepad first and then paste into the handout in Roll20 to avoid bringing over HTML formatting from the web site):<br />
<br />
<pre><br />
--/|ScriptCards Library: dnd5elib version 0.0.1<br />
--/|Provides various utility procedures for D&D 5E games<br />
<br />
--/|Lib5E_CheckDamageModifiers handle damage resistance, vulnerability, and immunity. <br />
--/|Pass a string variable to be filled with a string to be appended to a dice roll and the damage type <br />
<br />
--:Lib5E_CheckDamageModifiers|damageVariableName;damageType<br />
--&[%1%]|<br />
--?"[*T:npc_vulnerabilities]" -inc "[%2%]"|>_Lib5E_IsVulnerable;[%1%]<br />
--?"[*T:npc_resistances]" -inc "[%2%]"|>_Lib5E_IsResistant;[%1%]<br />
--?"[*T:npc_immunities]" -inc "[%2%]"|>_Lib5E_IsImmune;[%1%]<br />
--<|<br />
<br />
--:_Lib5E_IsVulnerable| --&[%1%]| * 2 [Vulnerable] --<|<br />
--:_Lib5E_IsResistant| --&[%1%]| \ 2 [Resistant] --<|<br />
--:_Lib5E_IsImmune| --&[%1%]| * 0 [Immune] --<|<br />
</pre><br />
<br />
The idea is that the functions in the library create a string that can be appended to a roll to modify the output based on resistances, so you pass Lib5E_CheckDamageModifiers the name of the string variable you want to use and the damage type. The variable (ResistType in this case) will include either nothing, “* 2 [Vulnerable]”, “\ 2 [Resistant]”, or “* 0 [Immune]” which can be included in a roll assignment (--=) to modify the damage as appropriate. The order here might be important if an NPC is misconfigured to be both resistant and immune to the same damage type. Since immune is an absolute, having it last ensures that it will override resistant or vulnerable. A creature that is both vulnerable and resistant (again, misconfigured) will come back as resistant since that condition is checked after vulnerable.<br />
Some notes: I prefix my library labels with either “Lib5E_” or “_Lib5E_” as a clarity convention. This isn’t strictly necessary but you should be aware that if two libraries (or if your script and a library) define the same label, the last label defined will win. Since libraries are appended to the end of the script in the order you include them in the +++libname+++ directive, you can somewhat control this, but it is probably best to avoid re-declaring labels. <br />
<br />
In my case, items beginning with “Lib5E_” are intended to be called by scripts, while items beginning with “_Lib5E_” are intended to be used as subroutines by the “public” procedures. Of course, there is no reason you couldn’t call them directly.<br />
<br />
You might also note that I’ve included some library information in comment lines (--/|) at the top of the library. These are ignored by ScriptCards, and are a good way to convey requirements, parameters, usage information, etc.<br />
<br />
=== Example Libraries ===<br />
<br />
==== dnd5elib ====<br />
<br />
[https://github.com/kjaegers/ScriptCards Download the dnd5elib Library from the ScriptCards GitHub]<br />
<br />
The '''dnd5elib''' library provides a collection of utility procedures that help simplify dealing with the D&D 5E Official Sheet. Some of the procedures in this library require '''chatsetattr''' to be installed in your game. This is a growing library, and currently only has a handful of routines. They are:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Procedure Name !! Notes<br />
|-<br />
| style="white-space:nowrap" | Lib5E_CheckDamageModifiers || This procedure can be used to evaluate vulnerabilities, resistances, and invulnerabilities on an NPC. After setting the --#target| parameters, pass the Lib5E_CheckDamageModifiers procedure a variable name (no reference information) and a damage type (i.e., fire, cold, bludgeoning, etc.), and the procedure will then create a string variable with with a name equal to the first parameter that you passed into the procedure. This variable will contain a string that can be included in a roll line (--=), in order to modify the roll as appropriate. For example, '''-->Lib5E_CheckDamageModifiers|ResistType;fire''' will check the current target character's attributes for "fire" and will either return an empty string (no references), "* 0 [Immune]" if the creature is immune, "\ 2 [Resistant]" if the creature is resistant, or "* 2 [Vulnerable]" if the creature is vulnerable to fire damage.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_DeductSpellSlot || Pass in a character_id and a slot level, and the script will expend one spell slot of that level, capping the value at 0 slots remaining. For Example '''<nowiki>-->Lib5E_DeductSpellSlot|@{selected|character_id};1</nowiki>''' to deduct a first level spell slot from the selected character.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_FindResource || Used to locate a resource value on a character. Pass in a character_id, a resource name, and two variable names. The procedure will check both repeating and non-repeating resources looking for a resource whose name matches what was passed in and return three variables. The first will be a string variable named for the 3rd parameter and contains the attribute name of the resource's "name" field. The second will be a string variable named after parameter 4 and contains the resource's value field attribute name, and the third variable is a Roll Variable, also named after the 4th parameter that contains the current resource value. Example: '''<nowiki>-->Lib5E_FindResource|@{selected|character_id};Crossbow bolts;ResName;ResValue</nowiki>''' will find "Crossbow bolts" as a resource on the character and return [&ResName] which is the name of the resource attribute, [&ResValue] which is the '''name of the attribute that stores the value''' and [$ResValue] which is the current numeric value of the resource.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Global_Attack_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Attack Modifiers (repeating_tohitmod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Bless" for 1d4 active and "Being Cool" for +2 active, I will get a return string " + 1d4 [Bless] + 2 [Being Cool]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Save_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Save Modifiers (repeating_savemod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Bless" for 1d4 active and "Being Cool" for +2 active, I will get a return string " + 1d4 [Bless] + 2 [Being Cool]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Skill_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Skill Modifiers (repeating_skillmod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Guidance" for 1d4 active and "Being Cool" for +2 active, I will get a return string " + 1d4 [Guidance] + 2 [Being Cool]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_AC_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Save Modifiers (repeating_savemod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Shield of Faith" with a value of 2 active, I will get a return string " + 2 [Shield of Faith]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Damage_Modifiers || Pass a character ID and TWO string variable to set the return value. The first string will be for normal damage, and the second will be the additional damage on a crit. This procedure will look through the Global Damage Modifiers (repeating_damagemod_*) for rows that are active (checked on the character sheet) and return two strings with the dice rolls and descriptions for them (for example, if I have "Sneak Attack" with a value of 1d6 normal and 1d6 critical damage active, I will get a return string " + 1d6 [Sneak Attack]" and another string of " + 1d6 [Sneak Attack CRIT]" that can be used in a dice rolls.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_DivineSmiteDice || Used to calculate the number of dice to be rolled for a paladin's Divine Smite. Pass a target token id, a spell slot level, and a string variable to be set to the dice roll amount based on the NPC_TYPE attribute of the target token. The returned variable will contain a dice roll (like "3d8" that can be used in a --= line)<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Character_Summary || Pass a character ID to outputs a mini character sheet, including clickable buttons for attacks, actions, legendary actions, etc. Will automatically detect a PC vs NPC and output the appropriate sections.<br />
|}<br />
<br />
Due to formatting issues with the Wiki, the library code has been moved to a [https://gist.github.com/kjaegers/52f6049ddd257f0a1288aca4bbde13c5 GITHUB GIT]. Please view the GIST in raw mode and copy the text and paste it into a handout called "ScriptCards Library dnd5elib" in your Roll20 Game.<br />
<br />
== What to Know if you are Coming from PowerCards ==<br />
<br />
''Note: This section is a work in progress.''<br />
<br />
While ScriptCards and PowerCard have very similar output goals, their internals and use are quite different. The table below summarizes some of the major differences between the scripts.<br />
<br />
::{| class="wikitable"<br />
|-<br />
! PowerCards !! ScriptCards <br />
|-<br />
| With a handful of exceptions, all lines in a PowerCard macro are intended to produce a line of output on the final card. || With ScriptCards, ONLY the <code>--+</code> and <code>--*</code> statement types produces output <br />
|-<br />
| PowerCards lines begin with two dashes (<code>--</code>) followed by a unique tag name for the line, followed by a vertical bar and the content for the line. || ScriptCards lines begin with two dashes (<code>--</code>) followed by a '''statement type identifier''', which is a single character that identifies the type of line to the interpreter. This is followed by a tag (frequently optional), a vertical bar, and the parameters for the statement being executed.<br />
|-<br />
| PowerCard macros are always processed top to bottom. Lines can be hidden so they don't output anything, but there is no looping or branching (<code>--SkipTo</code> looks like a branch, but it just hides all of the lines until the referenced label. || ScriptCards scripts support true branching, including direct branching (<code>--^</code>) and procedure branching (<code>--></code>) and (<code>--<</code>). Procedures support parameters and a call stack so procedures can be nested to call other procedures.<br />
|-<br />
| All lines in a PowerCards macro need to have unique tags because PowerCards builds the card as a single JavaScript object using the tag names to store what will be displayed. This is why repeated tag names always result in the last one being shown. || ScriptCards tags do not need to be unique, and in the case of many line types are optional.<br />
|-<br />
| PowerCards conditionals result in either showing or hiding the line they are on. || ScriptCards conditionals '''''only''''' support branching as the result of the comparison. This branching can be direct (a GOTO) or procedural (a GOSUB) '''''NOTE: As of version 1.2.0, ScriptCards also supports roll/string variable assignment as a result of conditional evaluation, and later versions introduced code blocks that can be implemented as a result of a conditional'''''<br />
|-<br />
| PowerCards relies on the Roll20 [[Quantum Roll]] server and [[Inline|inline rolls]] for all dice functions || ScriptCards includes its own dice roll parser, and '''''does not support''''' [[Inline|inline rolls]]. '''''Note: As of version 1.2.3, ScriptCards will parse [[Inline|inline rolls]], inserting their final value in the place of the roll in the macro, but they are not part of or parsed by the built-in roll parser'''''<br />
|-<br />
| PowerCards RollIDs (often mistaken for variables) are assigned by analyzing the results of an inline roll, and cannot be referenced in other rolls, so you can't roll a <code>1d4</code> and then roll a <code>1d20</code> and add the <code>1d4</code> result because all of the rolls happen on the chat server before PowerCards gets the macro text. || ScriptCards supports two types of variables: <code>Roll Variables</code> and <code>String Variables</code>. Because ScriptCards uses its own roll parser and is not dependent upon the chat server, rolls and their results can be used in other rolls, math functions, output, etc.<br />
|}<br />
<br />
== Example Scripts ==<br />
<br />
'''''Note: The features available in ScriptCards have changed drastically since these examples were written. While these should still work, there are in many cases better ways to do things using language features introduces after these were constructed. Please see the [https://github.com/kjaegers/ScriptCards/tree/main/ScriptExamples Script Examples] section of the official ScriptCards GitHub repository for more updated script examples.<br />
<br />
Below are some sample scripts that utilize the various statement types in ScriptCards:<br />
<br />
=== Divine Smite ===<br />
<br />
This script will prompt the user for a spell slot level to expend on a divine smite. It will check the target's npc_type to see if it is an Undead or Fiend, which adds an additional d8 to the smite roll.<br />
<br />
[[File:ScriptCards Divine Smite.png|Divine Smite Script Output]]<br />
<br />
<pre><br />
!scriptcard {{<br />
--#title|Divine Smite<br />
--=DiceCount|?{Spell Slot Level?|1|2|3|4|5|6|7|8|9} + 1<br />
--=IsFiendOrUndead|0<br />
--?"@{target|npc_type}" -inc fiend|>IsBoosted<br />
--?"@{target|npc_type}" -inc undead|>IsBoosted<br />
--=TotalDice|[$DiceCount] + [$IsFiendOrUndead]<br />
--=SmiteRoll|[$TotalDice]d8<br />
--#emoteText|@{selected|token_name} smites @{target|token_name}<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
--+Smite|deals [$SmiteRoll] radiant damage.<br />
--X|<br />
<br />
--:IsBoosted|<br />
--=IsFiendOrUndead|1<br />
--<|<br />
}}<br />
</pre><br />
<br />
==== How It Works ====<br />
<br />
The first line sets the "title" card parameter to "Divine Smite".<br />
<br />
Line 2 Shows a query to the user asking for the spell slot level, adds one and stores the value in the "DiceCount" Roll Variable. The query/dropdown is generated by the chat server prior to the script being executed.<br />
<br />
Line 3 defaults the "IsFiendOrUndead" Roll Variable to 0.<br />
<br />
Lines 4 and 5 compare the target's "npc_type" attribute (passed by the chat server as text) to see if they include either "undead" or "fiend". If true, the IsBoosted subroutine will be called. No parameters are passed to this subroutine.<br />
<br />
Line 6 sets the "TotalDice" variable to the base (DiceCount) number plus the IsFiendOrUndead number, which will be a 0 or a 1.<br />
<br />
Line 7 calculates "SmiteRoll" by rolling a number of d8 equal to the "TotalDice" value.<br />
<br />
Lines 8-10 set the parameters for the emote, which appears above the card content. By setting the sourceToken and the targetToken, their icons will appear in the emote surrounding the text describing the action.<br />
<br />
Line 11 is the only line that actually produces output on the card. It results in "Smite deals # radiant damage".<br />
<br />
Line 12 ends the script execution, preventing the script from continuing and running the subroutines out of context.<br />
<br />
Lines 14-16 are the IsBoosted subroutine, starting with the :IsBoosted label. The IsFiendOrUndead variable is set to 1, and a return from subroutine is executed.<br />
<br />
=== Magic Missile ===<br />
<br />
This script demonstrates using a loop and calling a subroutine to fire a number of missiles determine by the spell slot level used to cast the spell.<br />
<br />
[[File:ScriptCards_MagicMissile_Fixed.png|Magic Missile Script Output]]<br />
<br />
<pre><br />
!scriptcard {{ <br />
--#title|Magic Missile<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
--=MissileCount|?{Spell Slot Level?|1|2|3|4|5|6|7|8|9} + 2<br />
--=DisplayCount|1<br />
--=MissileDamage|0<br />
--#leftsub|Slot level ?{Spell Slot Level?}<br />
--#rightsub|Ranged Attack<br />
--#emoteText|Fred uses a level ?{Spell Slot Level?} spell slot to fire [$MissileCount.Total] missiles of magical force!<br />
--:MissileLoop|<br />
-->FireMissile|<br />
--=DisplayCount|[$DisplayCount] + 1<br />
--?[$DisplayCount] -le [$MissileCount]|MissileLoop<br />
--+Total|Total damage is [$MissileDamage]<br />
--X|<br />
<br />
--:FireMissile|<br />
--=ThisMissile|1d4 + 1<br />
--=MissileDamage|[$MissileDamage] + [$ThisMissile]<br />
--+Missile|[$DisplayCount.Total] Hits for [$ThisMissile] [b]force[/b] damage<br />
--<|<br />
}}<br />
</pre><br />
<br />
==== How It Works ====<br />
<br />
Lines 1-3 set the card title, the source token and the target token. Setting these tokens causes their icons/avatars to appear in the Emote section of the card.<br />
<br />
Line 4 asks the user what spell slot level they wish to use to cast magic missile. The number of missiles fired is equal to 2 plus the spell level, and this is stored in the MissileCount variable.<br />
<br />
Line 5 stores a 1 in the DisplayCount variable. This will be used to control the loop to determine the number of missiles fired and the missile number when displaying damage rolls.<br />
<br />
Line 6 initializes MissileDamage to 0<br />
<br />
Line 7 sets the left subtitle to the text "Slot Level #", where # is the spell slot level being used.<br />
<br />
Line 8 sets the right subtitle to the text "Ranged Attack".<br />
<br />
Line 9 sets the emoteText parameter with a description of the action, including the slot level and number of missiles fired.<br />
<br />
Line 10 is a label for the missile firing loop<br />
<br />
Line 11 Calls the "FireMissile" subroutine<br />
<br />
Line 12 increases the DisplayCount variable by 1<br />
<br />
Line 13 Checks to see if there are still missles to fire (DisplayCount <= MissileCount) and if so branches to MissileLoop<br />
<br />
Line 14 Displays the total damage dealt by the spell.<br />
<br />
Line 15 stops execution of the script to prevent out of context execution of the subroutine.<br />
<br />
Lines 76-21 are the FireMissile subroutine, beginning with the FireMissile label. The 1d4+1 is rolled and assigned to "ThisMissile". The result is added to the existing MissileDamage total, and a line for the current missile is displayed with the missile number and the damage for the missile.<br />
<br />
=== Longsword Attack ===<br />
<br />
This script demonstrates a standard 5E D&D melee weapon attack, including detection of misses, fumbles, hits, and critical hits. If installed, alterbars is used to decrement the target's BAR3 value by the damage dealt.<br />
<br />
[[File:ScriptCards Longsword.png|Longsword Script Output]]<br />
<br />
<pre><br />
!scriptcard {{<br />
--#title|Longsword<br />
--#leftsub|Melee Attack<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
--#emoteText|@{selected|token_name} attacks @{target|token_name}<br />
--=TargetAC|@{target|npc_ac}<br />
--?[$TargetAC.Total] -gt 0|DoneWithAC<br />
--=TargetAC|@{target|ac}<br />
--:DoneWithAC|<br />
--=AttackRoll|1d20 + @{selected|strength_mod} [STR] + @{selected|pb} [PROF]<br />
--+Attack|@{selected|token_name} rolls [$AttackRoll] vs AC [$TargetAC].<br />
--?[$AttackRoll.Base] -eq 20|Crit<br />
--?[$AttackRoll.Base] -eq 1|Fumble<br />
--?[$AttackRoll.Total] -ge [$TargetAC.Total]|Hit<br />
--+Miss|The attack missed.<br />
--^Final|<br />
<br />
--:Fumble|<br />
--+Fumble!|The attack went horribly wrong.<br />
--^Final|<br />
<br />
--:Hit|<br />
--=Damage|1d8 + @{selected|strength_mod} [STR]<br />
--+Hit!|The attack hit @{target|token_name} for [$Damage] slashing damage.<br />
--@alter|_target|@{target|token_id} _bar|3 _amount|-[$Damage]<br />
--^Final|<br />
<br />
--:Crit|<br />
--=Damage|1d8 + @{selected|strength_mod} [STR] + 1d8 [CRIT]<br />
--+Critical Hit!|The attack hit @{target|token_name} for [$Damage] slashing damage.<br />
--@alter|_target|@{target|token_id} _bar|3 _amount|-[$Damage]<br />
<br />
--:Final|<br />
}}<br />
</pre><br />
<br />
==== How it Works ====<br />
<br />
In lines 1-5, we set the title, subtitle, and emote text along with the tokens for the emote area.<br />
<br />
Lines 6-9 allow us to determine the AC of the target. On the 5E Roll20 sheet, NPCs armor class is stored in "npc_ac", while PCs armor class is in "ac". First we grab npc_ac and if it is zero, we check AC.<br />
<br />
Line 10 rolls the attack roll, rolling 1d20 and adding the attacker's strength modifier and proficiency bonus<br />
<br />
Line 11 displays the result of the attack roll on the card<br />
<br />
Lines 12-14 determine what kind of result the attack had. If the .Base value of the roll was 20, we branch to "Crit". If it was 1, we branch to "Fumble". If the .Total value of the roll was greater than or equal to the AC that was determined in Lines 6-9, we branch to Hit.<br />
<br />
Assuming we didn't branc anywhere, the result of the attack was a miss, so we display that on line 15 and then branch to "Final"<br />
<br />
This is followed by three branch segments, :Fumble, :Hit, and :Crit. A fumble displays a text message and branches to :Final.<br />
<br />
On a hit or a crit, we roll Damage (adding additional damage dice on a crit). We display a "Hit!" or "Critical Hit!" message and then make an API call to AlterBars, passing it the token id, bar we want to modify (3 in this case), and the amount we want to modify by the Damage value.<br />
<br />
=== Party Health Status ===<br />
<br />
This example calculates the current Hit Points remaining and HP percentage for each character and creates a color-coded display with the current party status.<br />
<br />
[[File:ScriptCards Party Health.png]]<br />
<br />
<pre><br />
!scriptcard {{<br />
--#title|Party Status<br />
--#titleCardBackground|#33CC33<br />
--#oddrowbackground|#bfee90<br />
--#evenrowbackground|#90eebf<br />
-->HealthCheck|@{Quej Grastra|character_id}<br />
-->HealthCheck|@{Brim Cheuto|character_id}<br />
-->HealthCheck|@{Odug Ututees|character_id}<br />
--X|End of card Execution<br />
<br />
--:HealthCheck|<br />
--=HealthPerc|[*[%1%]:hp] / [*[%1%]:hp^] * 100 \ 1<br />
--=HealthColor|000000<br />
--?[$HealthPerc.Total] -gt 50|HealthSkip<br />
--=HealthColor|FF0000<br />
--:HealthSkip|<br />
--+[*[%1%]:character_name]|has [#[$HealthColor.RollText]][*[%1%]:hp] of [*[%1%]:hp^][/#] HP [R]([$HealthPerc.Total]%)[/R]<br />
--<|End of HealthCheck<br />
}}<br />
</pre><br />
<br />
==== How it Works ====<br />
<br />
Lines 1-4, we set the card title, and set the title background and row background colors to shades of green.<br />
<br />
Lines 5-7 make gosub calls the the "HealthCheck" subroutine, passing in the character ID of each of the named characters (these are the names of the characters in my test game)<br />
<br />
Line 8 terminates the script execution.<br />
<br />
The remaining lines of the script are the HealthCheck subroutine, which works like this:<br />
<br />
Line 10 is the subroutine label (:HealthCheck)<br />
<br />
Line 11 uses the character id passed as a parameter and combines it with character attribute lookup *(...) to retrieve the value of "hp" and "hp<nowiki>^</nowiki>" for the character. The <nowiki>^</nowiki> character is used to specify that we want the MAX value for this attribute for the second call. We divide these two numbers and multiple by 100 to get a percentage. Finally, we use integer division by 1 to round the percentage and drop the decimals. The end result gets stored in the HealthPerc roll variable.<br />
<br />
Line 12 defaults to color of the health text to black<br />
<br />
Line 13 check to see if the health percentage is greater than 50. If so, it branches to HealthSkip, preventing the script from executing line 13.<br />
<br />
Line 14 sets the color of the health text to red<br />
<br />
Line 15 is the label that will be branched to from Line 13 to skip the red coloring<br />
<br />
Line 16 again uses character attribute substitution and the passed parameter value to output a display line containing the character name, the colorized health total, and the percentage value. The percentage is right-justified.<br />
<br />
Line 17 returns from the HealthCheck subroutine.<br />
<br />
=== Expanded Magic Missile Script ===<br />
<br />
This is the expanded and enhanced version of the Magic Missile script covered in {{yt|watch?v=u50xvNzS9Zk | this video}}. It includes visual and audio effects, checking and deducting spell slots, and applying damage using either Token-Mod or Alterbars.<br />
<br />
<pre><br />
!scriptcard {{ <br />
--#title|Magic Missile<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
<br />
-->GetAndCheckSlotInformation|<br />
<br />
--=MissileCount|[$SlotLevel] + 2<br />
--=DisplayCount|1<br />
--=MissileDamage|0<br />
--#leftsub|Slot level [$SlotLevel]<br />
--#rightsub|Ranged Attack<br />
--#emoteText|@{selected|character_name} uses a level [$SlotLevel.Total] spell slot to fire [$MissileCount.Total] missiles of magical force!<br />
<br />
--:MissileLoop|<br />
-->FireMissile|<br />
--=DisplayCount|[$DisplayCount] + 1<br />
--?[$DisplayCount] -le [$MissileCount]|MissileLoop<br />
--+Total|Total damage is [$MissileDamage]<br />
-->DeductSpellSlot|<br />
--#rightsub|Level [$SlotLevel] Left: [$SlotsRemaining] <br />
-->PlayEffects|none;burst-smoke;beam-magic;spell_01<br />
-->ApplyDamageTokenmod|@{target|token_id};3;-[$MissileDamage]<br />
-->ApplyDamageAlterbars|@{target|token_id};3;-[$MissileDamage]<br />
--X|<br />
<br />
--:FireMissile|<br />
--=ThisMissile|1d4 + 1<br />
--=MissileDamage|[$MissileDamage] + [$ThisMissile]<br />
--+Missile|[$DisplayCount.Total] Hits for [$ThisMissile] [b]force[/b] damage<br />
--<|<br />
<br />
--:GetAndCheckSlotInformation|<br />
--=SlotLevel|?{Spell Slot Level?|1|2|3|4|5|6|7|8|9}<br />
--=SlotsTotal|[*S:lvl[$SlotLevel]_slots_total]<br />
--=SlotsExpended|[*S:lvl[$SlotLevel]_slots_expended]<br />
--?[$SlotsExpended.Total] -ge [$SlotsTotal.Total]|NoSlotsLeft<br />
--<|<br />
<br />
--:NoSlotsLeft|<br />
--+|[*S:character_name] has no level [$SlotLevel.Total] spell slots available.<br />
--X|<br />
<br />
--:DeductSpellSlot|<br />
--=SlotsExpended|[$SlotsExpended] + 1<br />
--@setattr|_charid [*S:character_id] _lvl[$SlotLevel]_slots_expended|[$SlotsExpended] _silent<br />
--=SlotsRemaining|[$SlotsTotal] - [$SlotsExpended]<br />
--<|<br />
<br />
--:PlayEffects|Parameters are : source effect; target effect; line effect; sound effect<br />
--vtoken|@{selected|token_id} [%1%]<br />
--vtoken|@{target|token_id} [%2%]<br />
--vbetweentokens|@{selected|token_id} @{target|token_id} [%3%]<br />
--@roll20AM|_audio,play,nomenu|[%4%]<br />
--<|<br />
<br />
--:ApplyDamageTokenmod|Parameters are tokenid;bar#;amount<br />
--@token-mod|_ignore-selected _ids [%1%] _set bar[%2%]_value|[%3%]<br />
--<|<br />
<br />
--:ApplyDamageAlterbars|<br />
--@alter|_target|[%1%] _bar|[%2%] _amount|[%3%]<br />
--<|<br />
}}<br />
</pre><br />
<br />
===Hidden Roll===<br />
<br />
A roll where only the GM sees the result of the roll.<br />
[[File:Scriptcards-hiddenroll.png|right]]<br />
<pre><br />
!script {{<br />
--#title|Stealth Check<br />
--=Roll|1d20 + @{selected|stealth}<br />
--+|@{selected|token_name} attempts to move undetected...<br />
--*GMLine|@{selected|token_name} rolled a [$Roll]<br />
}}<br />
</pre><br />
<br />
===Elsewhere===<br />
* {{fpl|10000297/ Scritpcard API Working and Sharing}}<br />
* [https://gist.github.com/dubzilla1/cba439bd1f47ecdd81d0c79a482c4a91 Pathfinder 2E heal macros]<br />
<br />
[[Category:Featured articles]]</div>5004103https://wiki.roll20.net/Script:ScriptCardsScript:ScriptCards2022-02-10T18:58:51Z<p>5004103: /* Conditional Statement (--?) */</p>
<hr />
<div>{{revdate}}<br />
== Introduction ==<br />
'''ScriptCards''' provides a script interpreter that can be used to create powerful macros that display the results of player/NPC actions, or display other information in a pleasing visual format in your game's {{Text Chat}}. The scripting language contains variables (both dice-roll (enhanced numerics) and strings) as well, conditionals, branching, subroutines with parameters, and a set of built-in functions to simplify working with Roll20 information.<br />
{{script overview<br />
|name=ScriptCards<br />
|author=[[Kurt J.]]<br />
|code=ScriptCards<br />
|version=1.4.10<br />
|lastmodified=2021-12-04}}<br />
ScriptCards is not game-system specific, and can be used with any system/sheet. Near the end of this Wiki there is a section set aside for libraries that can implement system-specific tasks, with the hope that enthusiasts playing particular systems will create and share utility functions that can be utilized by the wider community.<br />
<br />
The default display style for ScriptCards output is similar to the format used to document player and NPC abilities in Dungeons and Dragons 4th Edition, but does not have any system ties to D&D4E.<br />
<br />
Current OneClick Version : 1.4.10<br />
'''''Note:''''' '''As of 2021-12-04, ScriptCards 1.4.10 has been submitted for OneClick update. The documentation below is in the process of being updated for 1.4.10.<br />
<br />
Current Development Version : 1.5.2<br />
<br />
'''''<big>Critically Important: ScriptCards does not use/parse [[Inline|inline rolls]]. ScriptCards includes its own built-in dice roll parser to allow for the use of variables inside dice rolls. As of version 1.2.3, ScriptCards will now take inline rolls and substitute the total result value in statement strings, meaning that you can utilize inline rolls but ScriptCards will only see the result of the roll, and not parse the roll components itself.</big>'''''<br />
{{#evp:youtube|hyR7Jnq4mQM|[[Script:ScriptCards|ScriptCards]] Introduction|right|650}}<br />
* {{fpl|9752053/ ScriptCards thread}}<br />
** {{fpl|10000297/ Scritpcard API Working and Sharing}}<br />
* {{repo|kjaegers/ScriptCards/tree/main/ScriptCards_API ScriptCards_API}} - GitHub repository for source before the one-click version is updated.<br />
* {{repo|kjaegers/ScriptCards/tree/main/ScriptExamples ScriptCards Samples}} - Branch of the GitHub repo that contains sample scripts.<br />
* {{yt.be|hyR7Jnq4mQM ScriptCards Intro}} 45min, Jan 2021<br />
* {{yt.be|u50xvNzS9Zk ScriptCards Magic Missile Deep Dive}} 39min, Feb 2021<br />
__TOC__<br />
=== Is ScriptCards Related to [[PowerCards]]? ===<br />
<br />
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.<br />
<br />
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 ({{code|name}}, {{code|leftsub}}, {{code|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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
Check the '''[[#What to Know if you are Coming from PowerCards|What to Know if you are Coming from PowerCards]]'''-section for a comparison table between the two scripts.<br />
<br />
=== What is a ScriptCard Script ===<br />
<br />
A ScriptCard Script is text written into the {{Text Chat}} (either typed directly, pasted, or run via a macro) that will produce a card of information in the [[Text Chat|chat window]]. A ScriptCard Script is composed of an [[API]] command: <code><nowiki>!scriptcard {{ }}</nowiki></code> enclosing any number of lines that determine the output that will be added to the card. At it simplest, the following macro:<br />
<br />
<pre>!scriptcard {{ }}</pre><br />
<br />
Will produce just a title card that displays “ScriptCards” as the name:<br />
<br />
[[File:Scriptcard blank.png]]<br />
<br />
Of course, this is just the simplest type of macro and isn’t very useful. In order to produce useful output, we need to include lines between the <code><nowiki>{{</nowiki></code> and <code><nowiki>}}</nowiki></code> that direct the API script as to what it should do.<br />
<br />
== Structure of a ScriptCard Line ==<br />
<br />
All ScriptCard lines begin with two dashes, followed by an ''statement identifier character'' that lets ScriptCards what type of line it is. There are several of these, and they are detailed in the next section. After the line type identifier, a Tag name 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.<br />
<br />
Following the Tag is a vertical bar, and then the content of the line itself. Again, each type of line might interpret this content differently.<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Identifier !! Statement Type !! Tag !! Content !! Notes<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--/</nowiki> || Comment || unused || unused || The <code>--/</code> 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--#</nowiki> || 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").<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--+</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--=</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--&</nowiki> || Assign String 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. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--@</nowiki> || 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 (i.e., [[TokenMod|!token-mod]], or [[ChatSetAttr|!setattr]], etc.)<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--:</nowiki> || 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<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--^</nowiki> || Branch To || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--></nowiki> || Call Procedure || 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<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--<</nowiki> || 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.<br />
|- <br />
| style="white-space:nowrap" | <nowiki>--?</nowiki> || Conditional Branch || Condition to be evaluated || True Branch Label<nowiki>|</nowiki>False Branch Label || The condition will be evaluated and execution will jump to one of the two indicated branches (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 included a semicolon separated list of parameters. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--s</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--l</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--v</nowiki> || 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+'''''<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--a</nowiki> || Play Audio Track || Unused || Jukebox track name (case sensitive) || Plays an audio track by name from the Roll20 jukebox. '''''Requires v1.5.2+'''''<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--e</nowiki> || Echo to Chat || Name to send chat command as || Chat message to send || Variable substitution takes place on the tag and content.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--R</nowiki> || Retrieve Repeating Section Row information || "find", "first", or "next" || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--~</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--c</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--i</nowiki> || Information Request || User Prompt;Button Caption || InfoType;VariableName;ParameterText || See full documentation below.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--d</nowiki> || 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. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--%</nowiki> || 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. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--*</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--!</nowiki> || Object Modification || <objectType>:<objectId> || setting:value|setting:value|setting:value... || Set properties of tokens/characters or character attributes ('''''v1.5.0+ required''''')<br />
|}<br />
<br />
== ScriptCard Statement Type Details ==<br />
The sections below detail the individual statement types supported by ScriptCards<br />
<br />
=== Comment (--/) ===<br />
<br />
A --/ statement is ignored by the ScriptCards parser. You can use this type of statement to add comments and informational text to your script. <br />
<br />
Example:<br />
<pre><br />
!script {{<br />
--/|Script Name : Fireball<br />
--/|Purpose : Allow the player to cast a fireball and blow stuff up!<br />
.<br />
.<br />
.<br />
}}<br />
</pre><br />
<br />
=== Set Parameter (--#) ===<br />
<br />
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.<br />
<br />
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.<br />
<br />
'''''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.'''''<br />
<br />
Examples:<br />
<pre><br />
--#title|Magic Missile<br />
--#leftsub|Level 1 Spell<br />
--#rightsub|Force Damage<br />
</pre><br />
<br />
The three examples above set the “title”, “leftsub”, and “rightsub” values for the card to the content value for the line. <br />
<br />
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.<br />
Settings Lines do not produce output lines on the card.<br />
<br />
The following settings are available (note that parameter names are ''not'' case sensitive):<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Name !! Effect/Use !! Default Value !! Type<br />
|-<br />
| 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<br />
|-<br />
| allowplaintextinrolls || If set to a non-zero value, plain character text in rolls will be copied to the roll text || 0 || Per-Line<br />
|-<br />
| bodyFontFace || Name of the font used in the card rows || Helvetica || Global<br />
|-<br />
| bodyFontSize || Size of the text in the card rows || 14px || Global<br />
|-<br />
| bodybackgroundimage || Specify an image (content for a CSS background-image tag) for the body area || none || Global<br />
|-<br />
| buttonBackground || Background color for buttons created with [button][/button] || #1C6EA4 || Per-Line<br />
|-<br />
| buttonBackgroundImage || A CSS specifier for a background image to use for buttons (i.e. url(...);) || empty || Per-Line<br />
|-<br />
| buttonBorderColor || Border (outline) color for buttons created with [button][/button] || #999999 || Per-Line<br />
|-<br />
| buttonFontFace || Font Family specifier for captions on buttons created with [button][/button] || Tahoma || Per-Line<br />
|-<br />
| buttonFontSize|| Text size for captions on buttons created with [button][/button] || x-small || Per-Line<br />
|-<br />
| buttonTextColor|| Text color of labels on buttons created with [button][/button] || #FFFFFF || Per-Line<br />
|-<br />
| 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<br />
|-<br />
| deferralcharacter || Changes the meta script deferral sequence to the specified value || ^ || Per-Line<br />
|-<br />
| diceFontColor|| Color of the dice created with the [d4] [d6], etc. formatting markers || #1C6EA4 || Per-Line<br />
|-<br />
| dicefontsize || Size of the dice created with the [d4] [d6], etc. formatting markers || 3.0em || Per-Line<br />
|-<br />
| 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<br />
|-<br />
| disablerollprocessing || If set to a non-zero value, --= lines will not process dice rolls strings || 0 || Per-Line<br />
|-<br />
| emoteBackground || Background color of the emote area || #f5f5ba || Global<br />
|-<br />
| emoteFont || Name of the font used in emote area (above the title of the output card) || Georgia || Global<br />
|-<br />
| emoteFontColor || Color of the font in the emote area || None (Empty) || Global<br />
|-<br />
| emoteFontSize || Size of the font used in the emote area || 14px || Global<br />
|-<br />
| emoteFontWeight || Font weight for the font in the emote area || bold|| Global<br />
|-<br />
| emoteState || If set to anything other than "visible", the emote portion of the card will not be displayed || visible || Global<br />
|-<br />
| emoteText || Text to display in the emote portion of the card || None (Empty) || Global<br />
|-<br />
| emotefont || Name of the font used in the emote text area || font-family: Georgia, serif; font-weight: bold; || Global<br />
|-<br />
| evenRowBackground || Hex code for the background color for even rows || #eeeeee || Per-Line<br />
|-<br />
| evenRowFontColor || Hex code for the text color for even rows || #000000 || Per-Line<br />
|-<br />
| evenrowbackgroundimage || Specify an image (content for a CSS background-image tag) for the even card rows || none || Per-Line<br />
|-<br />
| executionlimit || Maximum number of script lines the interpreter will try to execute. This prevents "infinite loop" sandbox crashes || 40000 || Global<br />
|-<br />
| hideCard || If set to any non-default value, the entire card output will be suppressed || 0 || Global<br />
|-<br />
| 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<br />
|-<br />
| 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<br />
|-<br />
| lineheight || Vertical size of each line on the output card || normal || Per-Line<br />
|-<br />
| nominmaxhighlight || If set to anything other than "0", rolls will not display crit/fumble/mixed highlight colors. || 0 || Per-Line<br />
|-<br />
| norollhighlight || If set to anything other than "0", rolls will not be formatted (plain numbers) but will still get a tooltip with details ('''''v1.3.6b+''''') || 0 || Per-Line<br />
|-<br />
| oddRowBackground || Hex code for the background color for even rows || #d0e4f5 || Per-Line <br />
|-<br />
| oddRowFontColor || Hex code for the text color for odd rows || #000000 || Per-Line<br />
|-<br />
| oddrowbackgroundimage || Specify an image (content for a CSS background-image tag) for the odd crd rows || none || Per-Line<br />
|-<br />
| reentrant || Used to name a script for rentrant button use || 0 || Global<br />
|-<br />
| 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)0 || Global<br />
|-<br />
| rollhilightcolorboth || Background box hilight color if both a 1 and a max on the die are rolled ('''''1.4.4+''''') || #8FA4D4 || Per-Line<br />
|-<br />
| rollhilightcolorcrit || Background box hilight color if the maximum number on the die was rolled ('''''1.4.4+''''') || #88CC88 || Per-Line<br />
|-<br />
| rollhilightcolorfumble || Background box hilight color if a 1 was rolled ('''''1.4.4+''''') || #FFAAAA || Per-Line<br />
|-<br />
| rollhilightcolornormal || Background box hilight color if neither a 1 or a max on the die are rolled ('''''1.4.4+''''') || #FFFEA2 || Per-Line<br />
|- <br />
| rollhilightlineheight || Determines the height of the hilight box placed around roll results ('''''1.4.2+''''') || 1.0em || Per-Line<br />
|-<br />
| roundUp || If set to a non-default value, integer division will round up instead of down || 0 || Per-Line<br />
|-<br />
| showfromfornonwhispers || If set to a non-zero value, will include the sender on cards that aren't whispered || 0 || Global<br />
|-<br />
| 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<br />
|-<br />
| subtitleFontColor || Color of the text in the subtitle areas || #FFFFFF || Global<br />
|-<br />
| subtitleFontFace || Name of the font used on the subtitle sections || Tahoma || Global<br />
|-<br />
| subtitleFontSize || Size of the subtitle font || 13px || Global<br />
|-<br />
| subtitleSeperator || The character(s) that will be placed between leftsub and rightsub || <nowiki>&#x2666</nowiki>; || Global<br />
|-<br />
| tableBorderRadius || CSS specifier for how rounded the borders of the output card are. Use "0px;" for square borders || 6px; || Global<br />
|-<br />
| tableShadow || CSS specifier for the drop shadow under the output card || 5px 3px 3px 0px #aaa; || Global<br />
|-<br />
| tablebgcolor || Background color of the whole card. '''''Normally not visible''''' || #EEEEEE || Global<br />
|-<br />
| tableborder || Color of the border that surrounds the whole card || 2px solid #000000; || Global<br />
|-<br />
| 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<br />
|-<br />
| timezone || IANA Specifier for the local time zone, used in system/date functions || America/New_York || Per-Line<br />
|-<br />
| title || Text displayed in the title area of the card || ScriptCards || Global<br />
|-<br />
| titleCardBackground || A hex color code representing the background color of the title area. || #1c6ea4 || Global<br />
|-<br />
| titleFontColor || Color of the text on the card title || #FFFFFF || Global<br />
|-<br />
| titleFontFace || Name of the font used on the title area || Contrail One || Global<br />
|-<br />
| titleFontLineHeight || Line spacing on the title area || 1.2em || Global<br />
|-<br />
| titleFontSize || Size of the title font || 1.2em || Global<br />
|-<br />
| titlecardbackgroundimage || Specify an image (content for a CSS background-image tag) for the title card area || none || Global<br />
|-<br />
| titlecardbottomborder || Border CSS specifier for the bottom of the title card area || 2px solid #444444; || Global<br />
|-<br />
| titlecardgradient || If set to non-zero value, will place a vertical gradient on the title card area || 0 || Global<br />
|-<br />
| usehollowdice || If set to a non-zero value, the hollow/outline versions of the dice fonts will be used || 0 || Per-Line<br />
|-<br />
| whisper|| Comma separated list of who to whisper the output to. Use "gm" for [[GM|GMs]] and "self" for the sender || none || Global|}<br />
|}<br />
<br />
''Setting Lines do not produce output lines on the card''<br />
<br />
=== Direct Output (--+) ===<br />
<br />
A direct output line display 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.<br />
<br />
Examples of Direct Output lines:<br />
<pre><br />
--+Hello|World<br />
--+Attack|The monster rolls [$Attack] to hit!<br />
--+Damage|@{target|token_name} is hit for [$Damage] [#3333AA][b]frost[/b][/#] damage.<br />
</pre><br />
<br />
Direct Output lines support inline formatting, roll variable replacement, character attribute references, and procedure variables.<br />
<br />
=== GM Output (--*) ===<br />
<br />
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. <br />
<br />
Example:<br />
<pre><br />
--+PlayerLine|This line is shown on the public card<br />
--*GMLine|This line will only be shown to GMs, on a separate card.<br />
</pre><br />
<br />
=== Roll Variable Assignment (--=) ===<br />
<br />
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.<br />
<br />
'''''All components of a roll equation should be separated with spaces.'''''<br />
<br />
Examples:<br />
<pre><br />
--=MissileDamage|1d4 + 1<br />
--=Attack|1d20 + @{selected|strength_mod} [STR] + @{selected|pb} [PROF]<br />
</pre><br />
<br />
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. Text enclosed in square brackets ([]) is considered "flavor text" and will be added to the result text but does not impact the roll result.<br />
<br />
The following dice formats are supported:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Format Pattern !! Example !! Description<br />
|-<br />
| XdY || 3d8 || Simple format. Roll a Y-sided die X times<br />
|-<br />
| XdYkhZ || 2d20kh1 || Roll Y-sided die X times and keep the highest Z number of dice<br />
|-<br />
| XdYklZ || 4d6kl3 || Roll Y-sided die X times and keep the lowest Z number of dice <br />
|-<br />
| XdY>Z || 5d6>3 || Roll Y-sided die X times and count a 1 for each roll greater than Z <br />
|-<br />
| XdY<Z || 5d6<3 || Roll Y-sided die X times and count a 1 for each roll less than Z <br />
|-<br />
| 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<br />
|-<br />
| 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<br />
|-<br />
| 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)<br />
|-<br />
| 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<br />
|-<br />
| 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).<br />
|-<br />
| 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.<br />
|-<br />
| 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. ('''''v1.5.1''''')<br />
|}<br />
<br />
The following operators are supported in a roll equation:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Operator !! Operation<br />
|-<br />
| + || Addition <br />
|-<br />
| - || Subtraction <br />
|-<br />
| * || Multiplication <br />
|-<br />
| / || Division <br />
|-<br />
| \ || Integer Division (Rounds down) <br />
|-<br />
| % || Modulo (Remainder of Divison)<br />
|}<br />
<br />
Roll Variables can be accessed at any time after they have been created by using the [$VariableName] format, with the following optional modifiers:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Modifier !! Meaning<br />
|-<br />
| No modifier || In a Direct Output Line (<nowiki>--+</nowiki>) 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<br />
|-<br />
| .Total || The end result of the roll equation as an unformatted number <br />
|-<br />
| .Base || The cumulative result of any dice rolled in the Roll Text (Numeric modifiers are not included) <br />
|-<br />
| .Ones || The number of dice in the roll that came up as 1s <br />
|-<br />
| .Aces || The number of dice in the roll that came up as the maximum number on the die <br />
|-<br />
| .Odds || The number of dice in the roll that came up with an odd number <br />
|-<br />
| .Evens || The number of dice in the roll that came up with an even number <br />
|-<br />
| .RollText || The raw text of the roll that was use to generate the results <br />
|-<br />
| .Text || A text representation of the results of the roll, including the numbers rolled for each die <br />
|-<br />
| .tableEntryText || The text portion of the result of a table roll<br />
|-<br />
| .tableEntryImgURL || The image source portion of the result of a table roll<br />
|-<br />
| .tableEntryValue || Numeric value of tableEntryText (via parseInt). If a non-numeric value, will be 0<br />
|-<br />
| .Raw || The total numeric result without any formatting, even if placed somewhere formatting would normally be done. <br />
|}<br />
<br />
Examples:<br />
<pre><br />
--+Total Damage|[$MissileDamage.Total] (roll was 1d4+1)<br />
--+Base Damage|[$MissileDamage.Base] (without the +1)<br />
--=Attack|1d20 + @{selected|strength_mod} [STR] + @{selected|pb} [PROF] + [$BlessBonus] [Bless]<br />
</pre><br />
<br />
In this case, 1d4 will be rolled and stored in “BlessBonus”, which can then be used in the Attack line.<br />
<br />
'''''Mathematical Functions in Roll Expressions '''''<br />
<br />
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:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Expression !! Meaning<br />
|-<br />
| {ABS} || Absolute Value<br />
|-<br />
| {CEIL} || Ceiling value (round up to the next whole number)<br />
|-<br />
| {FLOOR} || Floor value (round down to the next whole number)<br />
|-<br />
| {ROUND} || Round value (round up if the decimal portion is greater than 0.5, otherwise round down) '''Note: As of 1.4.11, ROUND now supports :X as a suffix to round to a given number of decimal places (ie, {ROUND:2}'''<br />
|-<br />
| {NEGATE} || Multiply the value by negative one.<br />
|-<br />
| {SQRT} || Take the square root of the running value.<br />
|-<br />
| {SQUARE} || Square the running value.<br />
|-<br />
| {CUBEROOT} || Take the cube root of the running value.<br />
|-<br />
| {CUBE} || Cube the running value.<br />
|-<br />
| {SIN} || Return the SIN of running value.<br />
|-<br />
| {COS} || Return the COS of running value.<br />
|-<br />
| {TAN} || Return the TAN of running value.<br />
|-<br />
| {ASIN} || Return the ASIN of running value.<br />
|-<br />
| {ACOS} || Return the ACOS of running value.<br />
|-<br />
| {ATAN} || Return the ATAN of running value.<br />
|-<br />
| {MAX:X} || Caps the running value at X. ('''''v1.4.12''''')<br />
|-<br />
| {MIN:X} || If the running value is less than X, set the value to X. ('''''v1.4.12''''')<br />
|-<br />
| {CLAMP:X:Y} || Adjust the running value to remain between X (lower bound) and Y (upper bound) ('''''v1.4.12''''')<br />
|}<br />
<br />
Here are the syntax rules when using the above listed functions:<br />
<br />
Example 1.<br />
<br />
<pre><br />
!script {{<br />
--=output|2.9 {FLOOR}<br />
--+output|[$output]<br />
}}<br />
</pre><br />
<br />
The output from this example is "2".<br />
<br />
Example 2.<br />
<br />
<pre><br />
!script {{<br />
--=output|2.9 {FLOOR} {NEGATE} - 3<br />
--+output|[$output]<br />
}}<br />
</pre><br />
<br />
The output from this example is "-5".<br />
<br />
Basically, a function will use as its input whatever the current "running total" is.<br />
<br />
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.<br />
<br />
<br />
'''''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 <nowiki>[[ ]]</nowiki> 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.<br />
<br />
'''''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.<br />
<br />
'''Rolling on Rollable Tables'''<br />
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.<br />
<br />
''Roll Variable Lines do not produce output lines on the card.''<br />
<br />
=== String Variable Assignment (--&) ===<br />
<br />
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:<br />
<br />
<pre><br />
--&MyText|Hello<br />
</pre><br />
<br />
Here, we assign the text "Hello" to the string variable named MyText. You can also append text to a string variable by prefixing the content with a + sign:<br />
<br />
<pre><br />
--&MyText|+ World<br />
</pre><br />
<br />
If run after the statement above, MyText will now contain "Hello World".<br />
<br />
String variables can be referenced using the syntax [&variablename]<br />
<br />
=== Call API (--@) ===<br />
<br />
ScriptCards can use a Call API instruction to execute other API commands. The Tag contains the API 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 API command is executed.<br />
<br />
Examples:<br />
<pre><br />
--@eh|list<br />
--@alter|_target|@{target|token_id} _bar|3 _amount|-[$Damage]<br />
</pre><br />
<br />
In the first example above, the command <code>!eh list</code> will be executed, calling [[EncounterHelper]]. In the second, {{fpl|1216260/ AlterBars}} is called to modify a token's Bar 3 value.<br />
<br />
'''''Note:''''' When ScriptCards (or any API script) runs other API 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).<br />
<br />
See [[API:Script Index]] for more options.<br />
<br />
=== Branch Label (--:) ===<br />
<br />
A branch label defines a line in your code that can be reached by one of the branching instructions (<nowiki>--^</nowiki>, <nowiki>--></nowiki>, or <nowiki>--?</nowiki>). The Tag serves as the label name, and must be unique on the card.<br />
<br />
The vertical bar (|) separator must be present, but the content portion of the line is unused and can be treated as a comment.<br />
<br />
Examples:<br />
<pre><br />
--:MyLoop|<br />
--:CriticalHit|Will jump here if we roll a critical hit!<br />
</pre><br />
<br />
''A Branch Label line does not produce an output line on the card.''<br />
<br />
=== Branch (--^) === <br />
<br />
A Branch line 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.<br />
<br />
Examples:<br />
<pre><br />
--^MyLoop|Jumps to MyLoop<br />
--^SkipCrit|We didn't crit, so skip the Crit code<br />
</pre><br />
<br />
''A Branch line does not produce an output line on the card.''<br />
<br />
=== Call Procedure (-->) ===<br />
<br />
Similar to a branch, a Call Procedure (sometimes knows 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 (<nowiki>--<</nowiki>) 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 (;).<br />
<br />
Examples:<br />
<pre><br />
-->FixFormat|#3333FF;#999999<br />
</pre><br />
<br />
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%].<br />
<br />
=== Return (--<) ===<br />
<br />
A return instruction marks the end of a Gosub procedure. 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.<br />
<br />
Examples:<br />
<pre><br />
--<|<br />
--<|End of MySub<br />
</pre><br />
<br />
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.<br />
<br />
=== Conditional Statement (--?) ===<br />
<br />
A conditional statement contains some equation in the Tag that will be evaluated. '''''If any part of the comparison can/does contain a space, it needs to be surrounded by double quotes'''''<br />
<br />
Based on the true/false result of the evaluation, one of two execution paths will be taken. These execution paths are detailed in the content section of the statement. The "if true" path is specified first (directly after the vertical bar), and the "if false" path is specified after it, also separated by a vertical bar.<br />
<br />
Example:<br />
<pre><br />
--?[$AttackRoll.Total] -ge [$TargetAC]|Hit|Miss<br />
</pre><br />
<br />
'''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.'''<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Branch Format !! Meaning<br />
|-<br />
| Label || If just a label is specified, execution will branch to that label when the comparison is matched.<br />
|-<br />
| >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 <br />
|-<br />
| =VariableName || The roll variable "VariableName" will be assigned the value following a semicolon (for example, "=Roll;1d20" will assign the value "1d20" to a variable named "Roll").<br />
|-<br />
| &VariableName || The string variable "VariableName" will be assigned the value following a semicolon (ex: --?1 -eq 1|&Result;Hit|&Result;Miss)<br />
|-<br />
| % or %! || The current for...next loop will perform the "next" action (%) or will break out (%!) <br />
|-<br />
| [ || Code block (see below)<br />
|}<br />
<br />
Examples:<br />
<pre><br />
--?[$AttackRoll.Base] -eq 20|CriticalHit<br />
--?[$AttackRoll.Base] -eq 1|>Fumble;@{selected|dexterity_mod}<br />
--?"@{target|npc_type}" -inc "undead"|&MonsterType;Undead|&MonsterType;Not Undead<br />
--?[$Attack.Total] >= [$ArmorClass]|>Hit|>Miss<br />
</pre><br />
<br />
In the first example, if the Base value of AttackRoll is a 20 (natural 20 on the die) execution will branch to the CriticalHit label.<br />
<br />
In the second example, 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%].<br />
<br />
The third example looks for the word "undead" in the npc_type attribute of the targeted character. If it exists in the text, the MonsterType string variable will be set to "Undead", otherwise it will be set to "Not Undead". <br />
<br />
The final example would call 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.<br />
<br />
''Text that does/may contain a space should be enclosed in double quotes.''<br />
<br />
The following comparison operators are available:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Comparator !! Meaning<br />
|-<br />
| -eq || Equal To <br />
|-<br />
| -eqi || Case insensitive Equal To <br />
|-<br />
| -ne || Not Equal To <br />
|-<br />
| -nei || Case insensitive Not Equal To <br />
|-<br />
| -gt || Greater Than <br />
|-<br />
| -ge || Greater Than or Equal To <br />
|-<br />
| -lt || Less Than <br />
|-<br />
| -le || Less Than or Equal To <br />
|-<br />
| -inc || Includes (text strings). <br />
|-<br />
| -ninc || Does Not Include (text strings). <br />
|}<br />
<br />
Multi-part conditionals are supported with -and and -or as separators. For example:<br />
<br />
<pre><br />
--?[$Attack.Total] -ge @{target|npc_ac} -and [$Attack.Base] -ne 20|HitButNotCrit<br />
</pre><br />
<br />
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):<br />
<br />
true AND false OR true<br />
<br />
Will be evaluated as true. The first two (true and false) will be false, but then false OR true will be true.<br />
<br />
Conversely:<br />
<br />
true or false and false<br />
<br />
Will be false, because the first true and false will evaluate to true, and then true and false will be false.<br />
<br />
'''CODE BLOCKS'''<br />
<br />
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.<br />
<br />
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:<br />
<br />
<pre><br />
!script {{<br />
--=Roll|1d2<br />
--+Roll|[$Roll]<br />
--?[$Roll.Total] -eq 2|[<br />
--&Value|Yep!<br />
--+|We are inside the TRUE portion of the block<br />
--]|[<br />
--&Value|Nope<br />
--+|We are inside the FALSE portion of the block<br />
--]|<br />
--+After|the blocks!<br />
--+Value|[&Value]<br />
}}<br />
</pre><br />
<br />
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 --]|. <br />
<br />
At this time, blocks cannot be nested, and can only be created as part of a conditional (--[ is not a valid statement type)<br />
<br />
''A conditional statement does not produce a line of output on the card.''<br />
<br />
=== Case Statement (--c) ===<br />
<br />
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 (:). Each match condition includes a branch label that will be used if the test value matches the item. 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:<br />
<br />
<pre><br />
!script {{<br />
--#title|Case Statement Testing<br />
--=Roll|1d4<br />
--C[$Roll.Total]|1:>One;[$Roll]|2:>Two;[$Roll]|3:>Three;[$Roll]|4:>Four;[$Roll]<br />
--X|<br />
<br />
--:One| --+Value|was One ([%1%]) --<|<br />
--:Two| --+Value|was Two ([%1%]) --<|<br />
--:Three| --+Value|was Three ([%1%]) --<|<br />
--:Four| --+Value|was Four ([%1%]) --<|<br />
}}<br />
</pre><br />
<br />
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 variable as a parameter.<br />
<br />
=== Save and Load (--s and --l) ===<br />
<br />
This statement pair is used to either store (--s) or load (--l) data from persistent storage. Items stored in persistent storage remain between card rolls and between Roll20 sessions. There are two types of data that can be stored: settings and roll variables. <br />
<br />
Examples:<br />
<br />
<pre><br />
--Ssettings|GreenStyle<br />
--Srollvariables|FirstCardVars<br />
</pre><br />
<br />
In this case, the tag for the statement determines what type of item is being saved (settings or rollvariables). When saving settings, all non-default settings are written to the named setting storage value. When Roll Variables are saved, all variables that currently exist will be saved to the named storage value.<br />
<br />
Loading stored items simply requires the same command with the --l statement type:<br />
<br />
<pre><br />
--Lsettings|GreenStyle<br />
--Lrollvariables|FirstCardVars<br />
</pre><br />
<br />
When loading settings, all stored settings will be applied to the current card settings. You can override settings by changing them after the load.<br />
<br />
When loading roll variables, the saved variables will be added to (or overwrite if they have the same name) any variables on the current card. This means it is safe to create roll variables before the load statement.<br />
<br />
'''Practical Uses'''<br />
The major intended use of persistent storage is for storing card formats for use in later scripts. For example, the following script:<br />
<br />
<pre><br />
!scriptcard {{<br />
--#titlecardbackground|#22CC22<br />
--#oddrowbackground|#cceecc<br />
--#evenrowbackground|#99ee99<br />
--Ssettings|@{selected|token_name}<br />
}}<br />
</pre><br />
<br />
Would save the titlecardbackground, oddrowbackground, and evenrowbackground settings to a saved list named after the selected token's name. When creating cards for that token to run later, you could include the line:<br />
<br />
<pre><br />
--Lsettings|@{selected|token_name}<br />
</pre><br />
<br />
To load all of the settings at once. By creating these setting sets for each character, you can specify a different color scheme for each character that can then be used in cards with a single formatting line.<br />
<br />
There is a supplemental ! command added to support saved settings:<br />
<br />
<pre><br />
!sc-liststoredsettings<br />
</pre><br />
<br />
Will produce a list of all stored setting names, with buttons to list the setting values stored in each group and a button to delete groups as needed.<br />
<br />
=== Visual Effects (--v) ===<br />
<br />
The --v statement can be used to create visual effects on the tabletop. The tag portion of the statement can be either "token" or "betweentokens". The content portion of the statement contains the required parameters for the effect generation, separated by spaces. If the effect is "none", no effect will be played. If any other value that doesn't match a Roll20 effect name will result in a burst-fire effect.<br />
<br />
For "token" effects, the parameters are the token id for the token the effect happens on, followed by the effect specifier.<br />
<br />
Example:<br />
<pre><br />
--vtoken|@{selected|token_id} burst-fire<br />
</pre><br />
<br />
For "betweentoken" effects, the parameters are the source token id, the target token id, and the effect specifier.<br />
<br />
Example:<br />
<pre><br />
--vbetweentokens|@{selected|token_id} @{target|token_id} beam-magic<br />
</pre><br />
<br />
'''''Version 1.2.8+'''''<br />
<br />
An additional effect specifier, "point" is available in 1.2.8+. This specifier allows you to create a visual effect at a designated X/Y pixel coordinate. Future updates will add custom-vfx support to this option. The parameters are the X and Y coordinates and the effect descriptor. As of version 1.2.9, you can also use custom effect specifiers with Point effects:<br />
<br />
<pre><br />
--vpoint|150 200 burst-fire<br />
</pre><br />
<br />
=== Audio Effects (--a) ===<br />
<br />
'''''Requires version 1.5.2+'''''<br />
<br />
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.<br />
<br />
<pre><br />
--a|SwordHitSound<br />
</pre><br />
<br />
No external APIs are required.<br />
<br />
=== Echo to Chat (--e) ===<br />
<br />
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.<br />
<br />
Example:<br />
<pre><br />
--eThe Ghost|/em hovers around @{selected|character_name}... BOO!<br />
</pre><br />
<br />
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).<br />
<br />
'''''Whispering'''''<br />
<br />
You can use the echo statement to send a whisper, but there's a trick to it. If you execute this code here:<br />
<br />
<pre><br />
--eThe Ghost|/w ExamplePlayerName Boo.<br />
</pre><br />
<br />
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.<br />
<br />
So, in conclusion, it's best to use something like this when you're sending a whisper:<br />
<br />
<pre><br />
!script {{<br />
--#hidecard|1<br />
--&sender|The Ghost<br />
--&receiver|ExamplePlayerName<br />
--&message|Boo.<br />
--e[&sender]|/w [&receiver] [&message]<br />
--eScriptCards|/w gm **Whispered from [&sender] to [&receiver]:** [&message] <br />
}}<br />
</pre><br />
<br />
This will ensure that the message appears in your chat feed as well.<br />
<br />
=== Repeating Section Access (--R) ===<br />
<br />
ScriptCards (as of v0.0.13) supports accessing repeating section rows on a character sheet (for example: the attacks, the items, and the repeating resources) with the --R statement type. <br />
<br />
There are three basic commands you can use with --R, and they are specified by <br />
the tag used:<br />
<br />
<br />
'''''The "find" tag'''''<br />
<br />
An Rfind statement is used to search through a repeating field. Here is the general form of such a statement.<br />
<br />
<pre><br />
--Rfind|characterid;EntryName;SectionPrefix;SearchField<br />
</pre><br />
<br />
This is the most direct way to access a repeating section row. Supplying the character ID, followed by what you are looking for (Greatsword, for example), followed by the character sheet's section prefix (repeating_attack), followed by the field to check what you are searching for (atkname) will load the matching section (if found) into the script parsers memory. For example:<br />
<br />
<pre><br />
--Rfind|@{selected|character_id};Greatsword;repeating_attack;atkname<br />
</pre><br />
<br />
Will look at the character's "repeating_attack" section for an entry with an atkname value equal to "Greatsword". Similarly:<br />
<br />
<pre><br />
--Rfind|@{selected|character_id};Bite;repeating_npcaction;name<br />
</pre><br />
<br />
Will look for a "Bite" action on an NPC's action list.<br />
<br />
<br />
'''''The "first" tag'''''<br />
<br />
<pre><br />
--Rfirst|characterid;section prefix<br />
</pre><br />
<br />
This form of the --R command will look at all of the entries in the specified repeating section and load the first one into memory:<br />
<br />
<pre><br />
--Rfirst|@{selected|character_id};repeating_attack<br />
</pre><br />
<br />
Would load the character's first "repeating_attack" row into memory.<br />
<br />
<br />
'''''The "next" tag'''''<br />
<br />
<pre><br />
--Rnext|<br />
</pre><br />
<br />
No parameters are required for --Rnext, which loads the next entry in the list that was obtained with "first" into memory.<br />
<br />
<br />
'''''Section prefixes and how to use them'''''<br />
<br />
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 open [[D&D 5E by Roll20|this page]], and search for the phrase "repeating sections".<br />
<br />
<br />
'''''Additional information'''''<br />
<br />
However a row is obtained, it will be parsed to replace any attribute references (ie, @{level}) with the corresponding character attribute.<br />
<br />
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".<br />
<br />
You can reference repeating attribute data using the syntax [*R:attributename] syntax (similar to referencing standard character attributes).<br />
<br />
Here are some examples:<br />
<br />
Display the details of the "Greatsword" PC attack:<br />
<br />
<pre><br />
!script {{<br />
--Rfind|@{selected|character_id};Greatsword;repeating_attack;atkname<br />
--+Attack Name|[*R:atkname]<br />
--+Base Damage|[*R:dmgbase]<br />
}}<br />
</pre><br />
<br />
[[File:Scriptcards repeating greatsword.png|Repeating Greatsword Attack]]<br />
<br />
List all of the actions an NPC can take (just actions, not legendary, etc.)<br />
<br />
<pre><br />
!script {{<br />
--#title|NPC Actions<br />
--#leftsub|@{selected|token_name}<br />
--Rfirst|@{selected|character_id};repeating_npcaction<br />
--:DisplayLoop|<br />
--?"[*R:name]" -eq NoRepeatingAttributeLoaded|Done<br />
--+Action:|[*R:name] [*R:attack_damage] [*R:attack_damagetype]<br />
--?"[*R:attack_damage2]" -eq ""|NoSecondaryDamage<br />
--+ |[*R:attack_damage2] [*R:attack_damagetype2]<br />
--:NoSecondaryDamage|<br />
--Rnext|<br />
-->DisplayLoop| <br />
--:Done|<br />
}}<br />
</pre><br />
<br />
[[File:Scriptcards repeating npcactions.png]]<br />
<br />
In the script above, we get the "first" repeating_npcaction and display information about it. We then execute "next" and repeat until we run into "NoRepeatingAttributeLoaded".<br />
<br />
See the section named [[#Repeating Section Values|Repeating Section Values]] for more information.<br />
<br />
<br />
'''''Special debugging command: dump'''''<br />
<pre><br />
--Rdump|<br />
</pre><br />
<br />
The "dump" command will list all of the attributes ScriptCards knows about for the currently loaded repeating row to the API Console Log.<br />
<br />
=== Assign Variable to Built-In Function (--~) ===<br />
<br />
ScriptCards has the ability to run a function built into the API script and return the results to a variable. Some functions return roll variables, while others return strings. See the function table below for details. The format is:<br />
<br />
--~VariableName|function;param1;param2;param3;...<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Function Name !! Parameters !! Description<br />
|-<br />
| distance || token_A_ID;token_B_ID || Calculate the Chebyshev distance in grid units between two tokens. This is the measurement scheme D&D 4E/5E use for diagonal distance measurement<br />
|-<br />
| euclideandistance || token_A_ID;token_B_ID || Calculate the Euclidean distance between two tokens. This is essentially the Pythagorean theorem in action. Returns the result in grid units.<br />
|-<br />
| euclideanpixel || token_A_ID;token_B_ID || Calculate the Euclidean distance between two tokens and returns the result is pixels instead of grid units. <br />
|-<br />
| euclideanlong || token_A_ID;token_B_ID || 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 is calculated instead of before. More accurate over long distances. <br />
|-<br />
| manhattandistance || token_A_ID;token_B_ID || Also called "taxicabdistance" (which is an acceptable function name), this measures to how-many-over, how-many-up/down distance, disallowing diagonal movement.<br />
|-<br />
| getselected || none || 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 the first selected token, VariableName2 the second, etc.<br />
|}<br />
<br />
'''''Functions with Sub Functions'''''<br />
<br />
Most ScriptCards functions are grouped into set as sub functions. The table below lists the major functions and their sub functions.<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Function Name !! Sub Function !! Parameters !! Return Type !! Description<br />
|-<br />
| array || define || arrayname;value1;value2;... || none || Creates an array called "arrayname" and adds value1, value2, etc. to the array<br />
|-<br />
| array || sort || arrayname || none || Sorts the specified array in place in ascending order (alphabetically)<br />
|-<br />
| array || numericsort || arrayname || none || Sorts the specified array in place in ascending order (numerically) ('''''v 1.4.10+ ''''')<br />
|-<br />
| array || add || arrayname;value1;value2;... || none || Adds value1, value2, ... to the existing array "arrayname"<br />
|-<br />
| array || remove || arrayname;value1;value2;... || none || Removes value1, value2, ... from the existing array "arrayname". Resets the array index to 0.<br />
|-<br />
| array || replace || arrayname;currentvalue;newvalue || none || Replaces all occurrences of "currentvalue" in "arayname" with "newvalue"<br />
|-<br />
| array || setatindex || arrayname;index;newvalue || none || Replaces the array item at index "index" with "newvalue"<br />
|-<br />
| array || getindex || arrayname || stringVariable || Retrieves the current index in "arrayname" and stores it in the supplied string variable<br />
|-<br />
| array || setindex || arrayname;newindex || none || Sets the current index in array "arrayname" to "newindex"<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| array || removeat || arrayname;indexposition || none || Removes the item at index "indexposition" from "arrayname". Resets the current array index to 0.<br />
|-<br />
| array || indexof || arrayname;searchvalue || stringVariable || Searches the array "arrayname" for and item with the value of "searchvalue" and, if found, returns the index of the first matching value or "ArrayError" if not found<br />
|-<br />
| array || getlength || arrayname || stringVariable || Returns the number of items in array "arrayname"<br />
|-<br />
| array || pagetokens || arrayname;tokenid;(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. 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.)<br />
|-<br />
| 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.<br />
|-<br />
| array || stringify || arrayname || stringVariable || Returns all of the items in "arrayname" as a string separated by semicolons (;)<br />
|-<br />
| array || fromstring || arrayname || delimiter;string || Creates an array from "string", splitting "string" on "delimiter" to separate the items<br />
|-<br />
| array || statusmarkers|| arrayname;tokenid || none|| Creates an array (arrayname) of the active statusmarkers (sometimes called Token Markers) for the specified tokenid<br />
|-<br />
| math || angle || math;angle;tokenid;tokenid|| rollVariable || Calculates the angle between two tokens and returns the value in degrees<br />
|-<br />
| math || ceil || math;ceil;value || rollVariable || Rounds '''value''' up to the next integer, dropping any decimal portion of the number<br />
|-<br />
| math || clamp || math;clamp;value;lowerBound;upperBound || rollVariable || Returns '''value''', but restricted to the range of '''loweBound''' and '''upperBound'''.<br />
|-<br />
| math || floor || math;floor;value || rollVariable || Rounds '''value''' down, dropping any decimal portion of the number<br />
|-<br />
| math || max || math;max;valueA;valueB || rollVariable || Returns the larger of '''valueA''' vs '''valueB'''<br />
|-<br />
| math || min || math;min;valueA;valueB || rollVariable || Returns the smaller of '''valueA''' vs '''valueB'''<br />
|-<br />
| math || round || math;round;value || rollVariable || Rounds '''value''' to the nearest integer<br />
|-<br />
| string || length || string;length;stringValue || rollVariable || Returns the length of '''stringValue''' in characters<br />
|-<br />
| string || before || string;before;searchText;stringValue || stringVariable || Searches '''stringValue''' for '''searchText''' and returns the portion of '''stringValue''' prior to that text<br />
|-<br />
| string || after || string;after;searchText;stringValue || stringVariable || Searches '''stringValue''' for '''searchText''' and returns the portion of '''stringValue''' after that text<br />
|-<br />
| string || left || string;left;count;stringValue || stringVariable || Returns the leftmost '''count''' characters of '''stringValue'''<br />
|-<br />
| string || right || string;right;count;stringValue || stringVariable || Returns the rightmost '''count''' characters of '''stringValue'''<br />
|-<br />
| string || replace || string;replace;searchText;replaceText;stringValue || stringVariable || Replaces '''searchText''' in '''stringValue''' with '''replaceText''' and returns the resulting string<br />
|-<br />
| string || replaceall || string;replace;searchText;replaceText;stringValue || stringVariable || Replaces all intances of '''searchText''' in '''stringValue''' with '''replaceText''' and returns the resulting string '''''Requires 1.2.9+'''''<br />
|-<br />
| string || trim || string;trim;stringValue || stringVariable || Removes leading and trailing spaces from stringValue and returns the result. <br />
|-<br />
| string || substring || string;substring;start;count;stringValue || stringVariable || Returns '''count''' characters starting at '''start''' from '''stringValue'''<br />
|-<br />
| 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.<br />
|-<br />
| string || tolowercase || string;tolowercase;stringValue || stringVariable || Converts the passed string to lower case and assigns to the passed variable name. <br />
|-<br />
| string || touppercase || string || stringVariable || Converts the passed string to upper case and assigns to the passed variable name. <br />
|-<br />
| 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. <br />
|-<br />
| 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.<br />
|-<br />
| 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'''.<br />
|-<br />
| turnorder || clear || none || none || Clears all entries from the {{Turn Tracker}}/Initiative<br />
|-<br />
| turnorder || addtoken || tokenid;trackervalue || none || Adds the token represented by "tokenid" to the initiative tracker with an initiavie value of "trackervalue"<br />
|-<br />
| turnorder || replacetoken || tokenid;trackervalue || none || Replaces the token represented by "tokenid" in the initiative tracker with an initiavie value of "trackervalue". Will add the token if it doesn't exist in the tracker.<br />
|-<br />
| turnorder || removetoken || tokenid || none || Removes the token represented by "tokenid" from the initiative tracker if it exists<br />
|-<br />
| turnorder || addcustom || textlabel;trackervalue || none || Add a custom text entry to the {{Turn Tracker}}/Initiative named "textlabel" with an initiative value of "trackervalue"<br />
|-<br />
| system || date || getdatetime || stringVariable || Returns the date time in the active timezone (see settings) <br />
|-<br />
| system || date || getdate || stringVariable || Returns the date in the active timezone (see settings) <br />
|-<br />
| system || date || gettime || stringVariable || Returns the time in the active timezone (see settings)<br />
|-<br />
| system || dumpvariables || "rolls", "string", or "array" || none || Dumps all of the defined variables of the indicated type to the console log<br />
|-<br />
| system || findability || system;findability;charactername;abilityname || stringVariable || Returns the object ID of the ability on the indicated character or "AbilityNotFound"<br />
|-<br />
|}<br />
<br />
Examples:<br />
<br />
<pre><br />
--~HowFarAway|distance;@{selected|token_id};@{target|token_id}<br />
</pre><br />
<br />
Returns the distance (Chebyshev) between the selected and target tokens and stores it in "HowFarAway".<br />
<br />
<pre><br />
--SelectedDudes|getselected<br />
</pre><br />
<br />
If 5 tokens were selected, 6 variables would be created: SelectedDudesCount (with a value of 5), SelectedDudes1, SelectedDudes2, SelectedDudes3, SelectedDudes4, SelectedDudes5.<br />
<br />
=== Information Request (--i) ===<br />
<br />
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.<br />
<br />
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.<br />
<br />
After the user has clicked the button and responded to the requests, ScriptCards will resume processing the script from where it left off.<br />
<br />
Here is an example “i” line:<br />
<br />
<pre><br />
--IScriptCards needs additional information to continue;Click to select a target and provide information|t;MyNewTarget;Missile1Target||q;MyNameIs;What is your name?<br />
</pre><br />
<br />
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.<br />
<br />
Supported information request types are “t” for target token, and “q” for query.<br />
<br />
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).<br />
<br />
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:<br />
<br />
<pre><br />
q;UserName;What is your name?|Fred|Bob|Sally|Nancy<br />
</pre><br />
<br />
Would have a dropdown menu with four choices.<br />
<br />
=== Object Modification (--!) ===<br />
<br />
'''''Requires ScriptCards version 1.5.0+'''''<br />
<br />
Object modification support is now available in ScriptCards. As of 1.5.0, you can use the --! command to modify object properties in the game. This may help reduce the reliance on the --@ command to run other API commands to modify token/character values. The biggest benefit of this is that the changes happen as the script is processing, so the new values are available right away. <br />
<br />
The format of the command is:<br />
<pre><br />
--!<objectType>:<objectId>|setting:value|setting:value|setting:value...<br />
</pre><br />
<br />
'''objectType''' can be one of "t" for token, "c" for character, or "a" for character attribute<br />
<br />
'''objectId''' can be a token id or a character id (or "S"/"T" for the Source/Target token/char defined with --#sourcetoken and --#targettoken)<br />
<br />
'''setting''' and '''value''' pairs can be chained in a single statement separated by | to impact more than one property/attribute with a single line<br />
<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
Examples:<br />
<br />
Set the value of bar1_value for the selected token to 5:<br />
<pre> --!t:@{selected|token_id}|bar1_value:5</pre><br />
Add 1 to the bar3_value for the selected token:<br />
<br />
<pre> --!t:@{selected|token_id}|bar3_value:+=1</pre><br />
Set bar2_value to 5 and bar2_max to 10 for the selected token<br />
<br />
<pre> --!t:@{selected|token_id}|bar2_value:5|bar2_max:10</pre><br />
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:<br />
<br />
<pre> --!a:@{selected|token_id}|dndstyling:on|size:enormous|!attitude:epic</pre><br />
Adds 50 to the npc_xp attribute for the character represented by the selected token, displaying the value before and after the update:<br />
<br />
<pre><br />
!script {{<br />
--+XP|[*@{selected|token_id}:npc_xp]<br />
--!a:@{selected|token_id}|npc_xp:+=50<br />
--+XP|[*@{selected|token_id}:npc_xp]<br />
}}<br />
</pre><br />
<br />
Note that asynchronous read/update fields (bio, notes, gmnotes) are not currently supported.<br />
<br />
== Inline Formatting ==<br />
<br />
Inline formatting is processed on Direct Output lines only (--+ lines) and the following inline format markup is available:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Formatting Tags !! Description<br />
|-<br />
| [b]..[/b] || Bold the text between the markers <br />
|-<br />
| [i]..[/i] || Italicize the text between the markers <br />
|-<br />
| [u]..[/u] || Underline the text between the markers <br />
|-<br />
| [s]..[/s] || Strike-Thru the text between the markers <br />
|-<br />
| [c]..[/c] || Center alignment <br />
|-<br />
| [l]..[/l] || Left alignment <br />
|-<br />
| [r]..[/r] || Right alignment <br />
|-<br />
| [j]..[/j] || Full justification alignment <br />
|-<br />
| [#xxx]..[/#] or [#xxxxxx]..[/#] || Use a 3 or 6 digit hex code to colorize the text between the markers <br />
|-<br />
| [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, <code>[img width=128 height=128]</code> )<br />
|-<br />
| [button]caption::action[/button] || Create a button with the label "caption" that performs the action defined by "action". By default, buttons will be colored according the the buttontextcolor and buttonbackground card settings. You can optionally color individual buttons by specifying a text color and a background color as part of the [button] command (ie, [button:#ffffff:#000000] will create a button with white text on a black background. In order to set a background color, the foreground color must be specified.<br />
|-<br />
| [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. By default, buttons will be colored according the the buttontextcolor and buttonbackground card settings. You can optionally color individual buttons by specifying a text color and a background color as part of the [sheetbutton] command (ie, [sheetbutton:#ffffff:#000000] will create a button with white text on a black background. In order to set a background color, the foreground color must be specified.<br />
|-<br />
| [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. By default, buttons will be colored according the the buttontextcolor and buttonbackground card settings. You can optionally color individual buttons by specifying a text color and a background color as part of the [rbutton] command (ie, [rbutton:#ffffff:#000000] will create a button with white text on a black background. In order to set a background color, the foreground color must be specified.<br />
|-<br />
| [t] || Converted to HTML table tag. Text after the "t" will be included inside the tag (width, border, etc)<br />
|-<br />
| [/t] || Converted to HTML close table tag.<br />
|-<br />
| [tr] || Converted to HTML table row tag. Text after the "tr" will be included inside the tag<br />
|-<br />
| [/tr] || Converted to HTML close table row tag.<br />
|-<br />
| [td] || Converted to HTML table cell tag. Text after the "tr" will be included inside the tag<br />
|-<br />
| [/td] || Converted to HTML close table cell tag.<br />
|}<br />
<br />
Code Example<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Formatting Tags !! Description<br />
|-<br />
| <pre>!script {{<br />
--#title|Inline Formatting Examples<br />
--+|This text [b]is bolded[/b]<br />
--+|This text [i]is italicized[/i]<br />
--+|This text [u]is underlined[/u]<br />
--+Alignment|[l]Left[/l]<br />
--+|[c]Center[/c]<br />
--+|[r]Right[/r]<br />
--+|[j]This long bit of text is justified to fit smoothly into the display area for the card with justified wrapping.[/j]<br />
--+Colorized|[#f00]Red[/#] [#0f0]Green[/#] [#00f]Blue[/#]<br />
--+Button|[button]Do Something::DoOnClick[/button]<br />
--+Button Colors|[button:#000:#f00]Red::RedClick[/button] [button:#000:#0f0]Blue::BlueClick[/button] [button:#000:#00f]Blue::BlueClick[/button]<br />
--+Table:|<br />
--+|[t border=2 width=100%][tr][td]Cell1[/td][td]Cell2[/td][/tr][tr][td]Cell3[/td][td]Cell4[/td][/tr][/t]<br />
}}</pre> || [[File:Sc-formatting_example.png]]<br />
|}<br />
<br />
== Variables ==<br />
<br />
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. While it is possible to assign both a string and a roll variable the same name, doing so will likely result in confusion when looking at the script later, so it is not recommended.<br />
<br />
String Variables are assigned with the --& statement and are referenced using [&variableName] notation.<br />
<br />
Roll Variables are assigned with the --= statement, and the assignment value is always processed by the ScriptCards Roll Processor (resolves dice rolls, etc.)<br />
<br />
There are a handful of variables assigned automatically when a ScriptCard is executed. These are all string variables, and are:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Variable !! Value<br />
|-<br />
| SendingPlayerID || Contains the object ID of the player that sent the macro<br />
|-<br />
| SendingPlayerName || Contains the display name of the player<br />
|-<br />
| SendingPlayerColor || Contains the color code associated with the player<br />
|-<br />
| SendingPlayerSpeakingAs || The contents of the "Speaking As" dropdown window<br />
|-<br />
| SendingPlayerIsGM || Contains 1 if the player is a GM, and 0 if the player is NOT a GM<br />
|}<br />
<br />
== Arrays ==<br />
<br />
Arrays are a special type of variable, and are managed by the function (<nowiki>--~</nowiki> command). All of the array function commands follow the same pattern:<br />
<br />
<pre>--~variableName|array;subcommand;arrayname;param1;param2;param3;...</pre><br />
<br />
Not all array commands return anything to "variableName". The function table above will specify the return type of the command if any.<br />
<br />
There are a couple of different ways to create an array:<br />
<br />
The '''define''' array subcommand creates (or recreates) an array and assigns it values - one for each included parameter after the array name. For example:<br />
<br />
<pre>--~|array;define;Fruits;mango;peach;strawberry;apricot;banana;apple</pre><br />
<br />
will create an array called '''Fruits''' with 6 elements in the order listed in the command (mango, peach, etc.)<br />
<br />
You can also use two other subcommands to create arrays based on tokens:<br />
<br />
<pre>--~Count|array;pagetokens;Everybondy;@{selected|token_id}</pre><br />
<br />
and<br />
<br />
<pre>--~Count|array;selectedtokens;Selected</pre><br />
<br />
In both cases, arrays of tokens will be created, and a string variable called "Count" will be set to the number of tokens in the array. The '''pagetokens''' command returns (by default) all of the tokens on the page that contains the token passed as the parameter after the array name. You can filter the tokens that "pagetokens" includes in the array by appending an optional parameter describing the type of token you are looking for:<br />
<br />
<pre>--~Count|array;pagetokens;Everybondy;@{selected|token_id};npc</pre><br />
<br />
Will return only tokens on the page that represent characters that do not have a ''controlledby'' parameter set. The available options are "all" (default), "char", "graphic", "pc", and "npc".<br />
<br />
The '''selectedtokens''' command returns an array with all of the tokens that were selected when the script was called.<br />
<br />
You can also use an arbitrary string to create an array, specifying a delimiter with the '''fromstring''' command:<br />
<br />
<pre><br />
--&names|Fred<br />
--&names|+,Sally<br />
--&names|+,Ted<br />
--&names|+,Joyce<br />
--~|array;fromstring;,;[&names]<br />
</pre><br />
<br />
The above example builds a comma-separated string and then uses "fromstring" to create an array with 4 elements from it, specifying the comma as the delimiter.<br />
<br />
Finally, you can use the '''statusmarkers''' command to create an array with one entry for each active status marker on a specified token:<br />
<br />
<pre>--~|array;statusmarkers;Conditions;@{selected|token_id}</pre><br />
<br />
will create an array with one entry for each status active on the selected token. The array elements will be the internal name of the status (if you are using custom status marker packs, the names will be specified in the marker pack).<br />
<br />
'''Traversing Arrays'''<br />
<br />
Each array keeps track of an internal index position (starting at 0). Several commands let you manage this index:<br />
<br />
*'''getindex''' returns the current index value<br />
*'''setindex''' sets the index to the specified location in the array<br />
*'''getlength''' returns the number of elements in the array<br />
*'''indexof''' returns the index location of the specified element<br />
<br />
Other commands let you retrieve values from the array:<br />
<br />
*'''getfirst''' sets the index to 0 and returns the value at that position<br />
*'''getnext''' advances the index by 1 and returns the new current value<br />
*'''getprevious''' reduces the index by 1 and returns the new current value<br />
*'''getlast''' sets the index to the last elements in the array and returns the new current value<br />
<br />
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.<br />
<br />
'''Manipulating Array Elements'''<br />
<br />
Several array commands deal with inserting, removing, and modifying elements:<br />
<br />
*'''add''' works just like define, except that it takes an existing array and adds elements to it based on the passed parameters<br />
*'''remove''' looks for items matching each passed parameter and removes them from the indicated array if they exist<br />
*'''removeat''' allows you to specify an index location in the array and remove the element at that position<br />
*'''replace''' searches an array for a value and replaces all occurrences of it with a new value (if found)<br />
*'''sort''' sorts the elements in the array in ascending order<br />
*'''strinfigy''' returns a string variable that includes each array element separated by semicolons (;) <br />
<br />
'''Referencing Array Elements'''<br />
<br />
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.<br />
<br />
<pre><br />
!script {{<br />
--~dummy|array;pagetokens;myarray;@{selected|token_id}<br />
--~count|array;getcount;myarray<br />
--+Total:|There are [&count] graphical objects on the page<br />
--~testvar|array;getfirst;myarray<br />
--:loop|<br />
--+Value|[*[&testvar]:character_name]<br />
--~testvar|array;getnext;myarray<br />
--?[&testvar] -ne ArrayError|loop<br />
--+Loop1|Is Done!<br />
}}<br />
</pre><br />
<br />
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:<br />
<br />
<pre><br />
!script {{<br />
--~dummy|array;pagetokens;myarray;@{selected|token_id}<br />
--~count|array;getcount;myarray<br />
--+Total:|There are [&count] graphical objects on the page<br />
--%loopCounter|1;[&count]<br />
--+Value|[*[@myarray([&loopCounter])]:character_name]<br />
--%|<br />
--+Loop|Is Done!<br />
}}<br />
</pre><br />
<br />
This line : <nowiki>--+Value|[*[@myarray([&loopCounter])]:character_name]</nowiki> uses [@arrayName(index)] format (inside a [*characterid:attribute] syntax) to perform the same task as running through the loop with the index.<br />
<br />
(Note: Additional examples are on the way...)<br />
<br />
== For...Next Loops ==<br />
<br />
For...Next loops in ScriptCards are supported with the with the --% statement type. A loop is defined by starting off with:<br />
<br />
<pre><br />
--%LoopCounter|<start>;<end>;[step]<br />
</pre><br />
<br />
The start and end values are required, while the step parameter is optional. If the step is omitted, it will be assumed to be 1. A string variable named after the line tag ("LoopCounter" in the case above) will be created and will hold the current iteration value for the loop. Here is a real example:<br />
<br />
<pre><br />
--%LoopCounter|1;10;1<br />
</pre><br />
<br />
This will begin a loop identified by "LoopCounter" that will start at 1, increasing by 1 each iteration (the step) until it has completed 10 executions.<br />
<br />
The "next" statement is simply <code>--%|</code>, with no tag or parameters. This indicates to ScriptCards that it should increment the counter and go back to the beginning of the loop. Extending the example above:<br />
<br />
<pre><br />
!script {{<br />
--%LoopCounter|1;10;1<br />
--=Roll|1d20<br />
--+Loop|Counter is [&LoopCounter], roll was [$Roll]<br />
--%|<br />
}}<br />
</pre><br />
<br />
The <code>--%!|</code> sequence will break out of the loop, no matter how many iterations are remaining.<br />
<br />
The % and %! character sequences can also be used as part of a 1.2.1+ non-branching conditional to continue or break the loop:<br />
<br />
<pre><br />
--?"X[&RollInto]X" -eq "XX"|%<br />
</pre><br />
<br />
In this example, if the string variable RollInfo is empty, the loop will return to the top and continue with the next iteration, while:<br />
<br />
<pre><br />
--?"X[&RollInto]X" -eq "XX"|%!<br />
</pre><br />
<br />
Would cause the whole loop to end if the condition were true.<br />
<br />
== Referencing ==<br />
<br />
=== Roll Variables===<br />
<br />
Roll Variables can be referenced from the content portion of any line type, and from the tag portion of conditional statements. The referenced value is replaced when the line is executed.<br />
<br />
There are several modifiers that can be used to reference parts of a roll:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Modifier !! Meaning<br />
|-<br />
| No modifier || In a Direct Output Line (<nowiki>--+</nowiki>), GM Output Line (<nowiki>--*</nowiki>), or String Assignement (<nowiki>--&</nowiki>), 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<br />
|-<br />
| .Total || The end result of the roll equation. Formatting rules for "No Modifier" apply based on line type. <br />
|-<br />
| .Raw || The total value of the roll variable without any formatting, no matter what kind of line the reference is used in.<br />
|-<br />
| .Base || The cumulative result of any dice rolled in the Roll Text (Numeric modifiers are not included) <br />
|-<br />
| .Ones || The number of dice in the roll that came up as 1s <br />
|-<br />
| .Aces || The number of dice in the roll that came up as the maximum number on the die <br />
|-<br />
| .Odds || The number of dice in the roll that came up with an odd number <br />
|-<br />
| .Evens || The number of dice in the roll that came up with an even number <br />
|-<br />
| .RollText || The raw text of the roll that was use to generate the results <br />
|-<br />
| .Text || A text representation of the results of the roll, including the numbers rolled for each die <br />
|-<br />
| .tableEntryText || The text portion of the result of a table roll<br />
|-<br />
| .tableEntryImgURL || The image source portion of the result of a table roll<br />
|-<br />
| .tableEntryValue || If the tableEntryText is purely numeric, will contain the numeric value<br />
|}<br />
<br />
=== String Variables ===<br />
<br />
To reference a string variable, use the notation [&variablename]. String variables can be referenced in direct output, roll variable assignment, and string variable assignment statements.<br />
<br />
=== Character/Token Attributes ===<br />
<br />
A character or token attribute can be referenced from content portion of any type of line and is substituted when the line is executed. The general format for referencing a character attribute is [*ID:attribute]. ID can be a token ID or a character ID (these start with a dash). Additionally if you have specified a sourceToken or targetToken, you can substitute "S" or "T" for the ID (for example [*S:npc_type] will retrieve the npc_type attribute from the source token.<br />
<br />
By default, all attribute references will be pulled from the '''''character''''' object that the ID represents (either directly or by being a Token ID that represents a character).<br />
<br />
Keep in mind, that if you want to access the "max" of a character attribute (for example, the max hit points), then you cannot trust the name that your roll20 character sheet shows you when you hover your mouse over the max hit points. For example, this reference will not work: [*S:hp_max]. Instead, you need to use this reference: [*S:hp^].<br />
<br />
If your ID refers to a token, token attributes can be accessed by preceding the attribute name with "t-", for example [*S:t-aura1_radius]. Supported token attributes are:<br />
<br />
{|<br />
| t-name || t-id || t-statusmarkers || t-bar1_value<br />
|-<br />
| t-bar1_max || t-bar2_value || t-bar2_max || t-bar3_value<br />
|-<br />
| t-bar3_max || t-top || t-left || t-width<br />
|-<br />
| t-height || t-rotation || t-layer || t-aura1_radius<br />
|-<br />
| t-aura1_color || t-aura2_radius || t-aura2_color || t-aura1_square<br />
|-<br />
| t-aura2_square || t-tint_color || t-light_radius || t-light_dimradius<br />
|-<br />
| t-light_angle || t-light_losangle || t-light_multiplier || t-light_otherplayers<br />
|-<br />
| t-light_hassight || t-flipv || t-fliph || t-controlledby<br />
|-<br />
| t-_cardid || t-_pageid || t-imgsrc || t-bar1_link<br />
|-<br />
| t-bar2_link || t-bar3_link || t-represents || t-layer<br />
|-<br />
| t-isdrawing || t-name || t-gmnotes || t-showname<br />
|-<br />
| t-showplayers_name || t-showplayers_bar1 || t-showplayers_bar2 || t-showplayers_bar3<br />
|-<br />
| t-showplayers_aura1 || t-showplayers_aura2 || t-playersedit_name || t-playersedit_bar1<br />
|-<br />
| t-playersedit_bar2 || t-playersedit_bar3 || t-playersedit_aura1 || t-playersedit_aura2<br />
|-<br />
| t-lastmove || t-adv_fow_view_distance || t-has_bright_light_vision || t-has_night_vision<br />
|-<br />
| t-night_vision_distance || t-emits_bright_light || t-bright_light_distance || t-emits_low_light<br />
|-<br />
| t-low_light_distance || t-has_limit_field_of_vision || t-limit_field_of_vision_center || t-limit_field_of_vision_total<br />
|-<br />
| t-has_limit_field_of_night_vision || t-limit_field_of_night_vision_center || t-limit_field_of_night_vision_total || t-has_directional_bright_light<br />
|-<br />
| t-directional_bright_light_center || t-directional_bright_light_total || t-has_directional_dim_light || t-directional_dim_light_center<br />
|-<br />
| t-directional_dim_light_total || t-lightColor || || |<br />
|}<br />
<br />
'''''It is important to note that some attributes names on tokens have corresponding attribute names on characters, which represent different values. For example, [*T:id] returns the character ID, while [*T:t-id] returns the token ID.'''''<br />
<br />
=== Subroutine Parameters ===<br />
<br />
When using a gosub statement (-->) or a conditional marked as a gosub (prefixing the label with a > character), you can pass any number of parameters separated by semicolons (;) that the code in the subroutine can utilize.<br />
<br />
Subroutine parameters are numbered starting at 1, and are accessed by using the notation [%number%], so the first parameter is [%1%], the second is [%2%], etc.<br />
<br />
Parameter substitution happens on all line types, and happens prior to character attribute references or roll variable substitution.<br />
<br />
=== Campaign Attribute ===<br />
You can retrieve properties of the API's Campaign object with the [*C:attributename] syntax. For example, [*C:playerpageid] will retrieve the current player ribbon page from the Campaign object.<br />
<br />
=== Page Attributes ===<br />
If you have set the '''activepage''' parameter, you can retrieve page-related properties with the [*P:attributename] syntax, including the page's UDL parameters.<br />
<br />
=== Repeating Section Values ===<br />
<br />
You can reference repeating attribute data using the syntax [*R:attributename] syntax (similar to referencing standard character attributes). The currently active repeating row information will be used to retrieve attribute values. You can also retrieve the full attribute name for a repeating row attribute by using the [*R>attributename] notation. This is useful to pass to things like chatsetattr.<br />
<br />
See the section named [[#Repeating Section Access (--R)|Repeating Section Access]] for more information.<br />
<br />
=== Array Elements ===<br />
After an array has been declared, the elements can be referenced with [@arrayName(index)]. Array indices start at 0.<br />
<br />
== Deferred Resolution for Meta Scripts ==<br />
<br />
As of 1.2.9, ScriptCards supports a deferral character for use when calling another API script with via the <code>--@</code> statement, to defer processing of meta script references so they get processed prior to the sub-API call instead of prior to ScriptCards execution. To defer this processing for meta script ([[Tim#SelectManager|SelectManager]], [[Tim#Fetch|Fetch]]) by inserting a deferral character into the meta call. For example, if I want to have ScriptCards call [[TokenMod]] as if the token for "Quej Gr'stra" (yes, I let Roll20 name my test NPCs) I could use something like this:<br />
<br />
<pre> --@token-mod|{^& select Quej Gr'stra} _on showname</pre><br />
<br />
The <code>^</code> in between <code>{</code> and <code>&</code> will prevent SelectManager from seeing the call when the ScriptCard script is processed, but the <code>--@</code> statement will remove the deferral character so the command that will be sent by ScriptCards is:<br />
<br />
<pre>!token-mod {& select Quej Gr'stra} --on showname</pre><br />
<br />
With the deferral character removed, SelectManager will see the <code>{& select ...}</code> and do its magic.<br />
<br />
While the default deferral character is <code>^</code>, the deferral character is a setting that can be changed:<br />
<br />
<pre> --#deferralcharacter|%</pre><br />
<br />
Will make <code>%</code> the deferral character for future <code>--@</code> statements in the running script.<br />
<br />
Supported [[API:Meta_Scripts|Meta Script]] structures:<br />
* <code>{^&...}</code> - for [[Tim#SelectManager|SelectManager]]<br />
* <code>@^(...)</code> and <code>*^(...)</code> for [[Tim#Fetch|Fetch]]<br />
* <code>get^.</code> and <code>set^.</code> for [[Tim#Fetch|Muler]] (''''' v 1.4.5+ ''''')<br />
<br />
== Arrays ==<br />
<br />
Arrays are a new data type introduced in version 1.1.12 of ScriptCards, and are manipulated with associated function (--~) commands.<br />
<br />
* Arrays are a lists of strings. Items in an array cannot contain the semi-colon (;) character, as that is used to separate parameters in the function code that deals with arrays.<br />
* Arrays are accessed via the --~ script command. In some cases, the value of the tag (variable name) for array commands is not used, and can be a dummy value or simply omitted. I have omitted them in the statements below.<br />
* All commands that DO return a value return string values, even if the content is numeric.<br />
* If a command returns a value and there is some sort of reason that it isn't an array value, you will get "ArrayError" in the return value. This can happen if you reach the end of an array while stepping through it, for example, so checking for "ArrayError" can serve as the end condition for a loop.<br />
* Each array keeps track of its current index, allowing you to step forward and backwards through arrays.<br />
* Any number of arrays can be defined.<br />
* Unlike string variables and roll variables, array variables cannot (currently) be referenced directly. It is necessary to use the function (--~) syntax to manipulate arrays and get values from them as strings for use in other parts of your script.<br />
<br />
== Reentrant Scripts ==<br />
<br />
Reentrant scripts allow you to create buttons in your script code that will re-execute the script at a given label within the code. If you set the reentrant setting (<code>--#reentrant|somevalue</code>) to a non-zero value, your setting and variable information will be preserved between executions. Reentrant script can be used to present menus or choices and then continue acting.<br />
<br />
'''''Important''''': The value of the reentrant setting will be used to identify the appropriate script to resume when reentrancy is used. If more than one character can potentially run the same script at the same time, it is a good practice to include the character ID in the reentrant setting in order to maintain a separate list of variables. Something like:<br />
<br />
<pre><br />
--#reentrant|My Cool Script @{selected|character_id}<br />
</pre><br />
<br />
Reentrant buttons are created with the <code>[rbutton]Caption::ReentryLabel;Parameter[/rbutton]</code> construct. The caption will be displayed on the generated button. <code>ReentryLabel</code> is the name of a label in your script that the button will jump to when clicked, and Parameter will be passed in as a string value called <code>reentryval</code>.<br />
<br />
Example:<br />
<pre><br />
!script {{<br />
--#reentrant|testing<br />
--=Roll|1d20<br />
--+Roll|[$Roll]<br />
--&String|That was a [$Roll.Raw]!<br />
--~x|array;define;MyArray;Apple;Banana;Orange<br />
--+Try it|[rbutton]Hello!::EXEC_PC_SPELL;9[/rbutton]<br />
--X|<br />
<br />
--:EXEC_PC_SPELL|<br />
--+ReentryVal|[&reentryval]<br />
--+The value of Roll is|[$Roll]<br />
--+Value of String|[&String]<br />
--+Array|[@MyArray(0)]<br />
--X|<br />
}}<br />
</pre><br />
<br />
This script sets up some variables and then displays a button labeled "Hello!". If the user clicks the button, the script will be re-entered starting at <code>EXEC_PC_SPELL</code>, which will display the content of the variables from the original execution.<br />
<br />
'''''Note: This section needs to be expanded upon'''''<br />
<br />
==Libraries ==<br />
=== Procedure Libraries ===<br />
<br />
You can now create [[handouts]] in your game in Roll 20 with the name format "ScriptCards Library NAME", where name is a name you assign to the library. Library names are case sensitive. It is my hope that the more proficient ScriptCards scripters out there will provide procedure libraries (or procedures that can be included in libraries) for others to use to make their scripting life easier. Be they specific to a game system, or to a type of activity, I think a robust set of libraries that GMs could use to enhance their scripting capabilities would be very valuable to the community. Should such things begin to emerge, I’ll create a portion of the ScriptCards Wiki page to house them.<br />
<br />
To include one or more libraries in a script, use the +++libname+++ directive (does not need a -- line associated with it). Multiple library names can be specified by separating them with semicolons (i.e., +++General;dnd5elib;Colorize+++ would include three libraries (General, dnd5elib, and Colorize).<br />
<br />
Included libraries are separated from the main script code by the automatic inclusion of "--X|" before the first library is appended to the script, and all libraries are loaded at the end of the script before script processing takes place.<br />
<br />
Procedures and labels in libraries can be used just as if they were included in the body of your script. Note that this DOES mean that you could, technically, jump into a library with a direct branch (--^) or direct branch conditional, but I recommend using libraries to store reusable procedures.<br />
The Notes section of the library handout stores the library code, and is written just like any other ScriptCards code except:<br />
<br />
* They cannot use roll queries (?{Some Prompt:}) to get information from the user at execution time.<br />
* They cannot use @{} notation to access character and token information.<br />
<br />
Both of these limitation stem from the fact that Procedure Libraries are not processed by the chat server, which is what handles these items.<br />
<br />
Here is an example of handling damage modifications (resistance, vulnerability, and immunity) in D&D 5E with a library:<br />
<br />
<pre><br />
!script {{<br />
+++dnd5elib+++<br />
--#|Damage Modifiers Test<br />
--#targettoken|@{target|token_id}<br />
-->Lib5E_CheckDamageModifiers|ResistType;fire<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] fire damage<br />
<br />
-->Lib5E_CheckDamageModifiers|ResistType;cold<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] cold damage<br />
<br />
-->Lib5E_CheckDamageModifiers|ResistType;poison<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] poison damage<br />
<br />
-->Lib5E_CheckDamageModifiers|ResistType;acid<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] acid damage<br />
<br />
--X|<br />
}}<br />
</pre><br />
<br />
Library content (In a handout called “ScriptCards Library dnd5elib” NOTE: Paste into Notepad first and then paste into the handout in Roll20 to avoid bringing over HTML formatting from the web site):<br />
<br />
<pre><br />
--/|ScriptCards Library: dnd5elib version 0.0.1<br />
--/|Provides various utility procedures for D&D 5E games<br />
<br />
--/|Lib5E_CheckDamageModifiers handle damage resistance, vulnerability, and immunity. <br />
--/|Pass a string variable to be filled with a string to be appended to a dice roll and the damage type <br />
<br />
--:Lib5E_CheckDamageModifiers|damageVariableName;damageType<br />
--&[%1%]|<br />
--?"[*T:npc_vulnerabilities]" -inc "[%2%]"|>_Lib5E_IsVulnerable;[%1%]<br />
--?"[*T:npc_resistances]" -inc "[%2%]"|>_Lib5E_IsResistant;[%1%]<br />
--?"[*T:npc_immunities]" -inc "[%2%]"|>_Lib5E_IsImmune;[%1%]<br />
--<|<br />
<br />
--:_Lib5E_IsVulnerable| --&[%1%]| * 2 [Vulnerable] --<|<br />
--:_Lib5E_IsResistant| --&[%1%]| \ 2 [Resistant] --<|<br />
--:_Lib5E_IsImmune| --&[%1%]| * 0 [Immune] --<|<br />
</pre><br />
<br />
The idea is that the functions in the library create a string that can be appended to a roll to modify the output based on resistances, so you pass Lib5E_CheckDamageModifiers the name of the string variable you want to use and the damage type. The variable (ResistType in this case) will include either nothing, “* 2 [Vulnerable]”, “\ 2 [Resistant]”, or “* 0 [Immune]” which can be included in a roll assignment (--=) to modify the damage as appropriate. The order here might be important if an NPC is misconfigured to be both resistant and immune to the same damage type. Since immune is an absolute, having it last ensures that it will override resistant or vulnerable. A creature that is both vulnerable and resistant (again, misconfigured) will come back as resistant since that condition is checked after vulnerable.<br />
Some notes: I prefix my library labels with either “Lib5E_” or “_Lib5E_” as a clarity convention. This isn’t strictly necessary but you should be aware that if two libraries (or if your script and a library) define the same label, the last label defined will win. Since libraries are appended to the end of the script in the order you include them in the +++libname+++ directive, you can somewhat control this, but it is probably best to avoid re-declaring labels. <br />
<br />
In my case, items beginning with “Lib5E_” are intended to be called by scripts, while items beginning with “_Lib5E_” are intended to be used as subroutines by the “public” procedures. Of course, there is no reason you couldn’t call them directly.<br />
<br />
You might also note that I’ve included some library information in comment lines (--/|) at the top of the library. These are ignored by ScriptCards, and are a good way to convey requirements, parameters, usage information, etc.<br />
<br />
=== Example Libraries ===<br />
<br />
==== dnd5elib ====<br />
<br />
[https://github.com/kjaegers/ScriptCards Download the dnd5elib Library from the ScriptCards GitHub]<br />
<br />
The '''dnd5elib''' library provides a collection of utility procedures that help simplify dealing with the D&D 5E Official Sheet. Some of the procedures in this library require '''chatsetattr''' to be installed in your game. This is a growing library, and currently only has a handful of routines. They are:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Procedure Name !! Notes<br />
|-<br />
| style="white-space:nowrap" | Lib5E_CheckDamageModifiers || This procedure can be used to evaluate vulnerabilities, resistances, and invulnerabilities on an NPC. After setting the --#target| parameters, pass the Lib5E_CheckDamageModifiers procedure a variable name (no reference information) and a damage type (i.e., fire, cold, bludgeoning, etc.), and the procedure will then create a string variable with with a name equal to the first parameter that you passed into the procedure. This variable will contain a string that can be included in a roll line (--=), in order to modify the roll as appropriate. For example, '''-->Lib5E_CheckDamageModifiers|ResistType;fire''' will check the current target character's attributes for "fire" and will either return an empty string (no references), "* 0 [Immune]" if the creature is immune, "\ 2 [Resistant]" if the creature is resistant, or "* 2 [Vulnerable]" if the creature is vulnerable to fire damage.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_DeductSpellSlot || Pass in a character_id and a slot level, and the script will expend one spell slot of that level, capping the value at 0 slots remaining. For Example '''<nowiki>-->Lib5E_DeductSpellSlot|@{selected|character_id};1</nowiki>''' to deduct a first level spell slot from the selected character.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_FindResource || Used to locate a resource value on a character. Pass in a character_id, a resource name, and two variable names. The procedure will check both repeating and non-repeating resources looking for a resource whose name matches what was passed in and return three variables. The first will be a string variable named for the 3rd parameter and contains the attribute name of the resource's "name" field. The second will be a string variable named after parameter 4 and contains the resource's value field attribute name, and the third variable is a Roll Variable, also named after the 4th parameter that contains the current resource value. Example: '''<nowiki>-->Lib5E_FindResource|@{selected|character_id};Crossbow bolts;ResName;ResValue</nowiki>''' will find "Crossbow bolts" as a resource on the character and return [&ResName] which is the name of the resource attribute, [&ResValue] which is the '''name of the attribute that stores the value''' and [$ResValue] which is the current numeric value of the resource.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Global_Attack_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Attack Modifiers (repeating_tohitmod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Bless" for 1d4 active and "Being Cool" for +2 active, I will get a return string " + 1d4 [Bless] + 2 [Being Cool]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Save_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Save Modifiers (repeating_savemod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Bless" for 1d4 active and "Being Cool" for +2 active, I will get a return string " + 1d4 [Bless] + 2 [Being Cool]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Skill_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Skill Modifiers (repeating_skillmod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Guidance" for 1d4 active and "Being Cool" for +2 active, I will get a return string " + 1d4 [Guidance] + 2 [Being Cool]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_AC_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Save Modifiers (repeating_savemod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Shield of Faith" with a value of 2 active, I will get a return string " + 2 [Shield of Faith]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Damage_Modifiers || Pass a character ID and TWO string variable to set the return value. The first string will be for normal damage, and the second will be the additional damage on a crit. This procedure will look through the Global Damage Modifiers (repeating_damagemod_*) for rows that are active (checked on the character sheet) and return two strings with the dice rolls and descriptions for them (for example, if I have "Sneak Attack" with a value of 1d6 normal and 1d6 critical damage active, I will get a return string " + 1d6 [Sneak Attack]" and another string of " + 1d6 [Sneak Attack CRIT]" that can be used in a dice rolls.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_DivineSmiteDice || Used to calculate the number of dice to be rolled for a paladin's Divine Smite. Pass a target token id, a spell slot level, and a string variable to be set to the dice roll amount based on the NPC_TYPE attribute of the target token. The returned variable will contain a dice roll (like "3d8" that can be used in a --= line)<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Character_Summary || Pass a character ID to outputs a mini character sheet, including clickable buttons for attacks, actions, legendary actions, etc. Will automatically detect a PC vs NPC and output the appropriate sections.<br />
|}<br />
<br />
Due to formatting issues with the Wiki, the library code has been moved to a [https://gist.github.com/kjaegers/52f6049ddd257f0a1288aca4bbde13c5 GITHUB GIT]. Please view the GIST in raw mode and copy the text and paste it into a handout called "ScriptCards Library dnd5elib" in your Roll20 Game.<br />
<br />
== What to Know if you are Coming from PowerCards ==<br />
<br />
''Note: This section is a work in progress.''<br />
<br />
While ScriptCards and PowerCard have very similar output goals, their internals and use are quite different. The table below summarizes some of the major differences between the scripts.<br />
<br />
::{| class="wikitable"<br />
|-<br />
! PowerCards !! ScriptCards <br />
|-<br />
| With a handful of exceptions, all lines in a PowerCard macro are intended to produce a line of output on the final card. || With ScriptCards, ONLY the <code>--+</code> and <code>--*</code> statement types produces output <br />
|-<br />
| PowerCards lines begin with two dashes (<code>--</code>) followed by a unique tag name for the line, followed by a vertical bar and the content for the line. || ScriptCards lines begin with two dashes (<code>--</code>) followed by a '''statement type identifier''', which is a single character that identifies the type of line to the interpreter. This is followed by a tag (frequently optional), a vertical bar, and the parameters for the statement being executed.<br />
|-<br />
| PowerCard macros are always processed top to bottom. Lines can be hidden so they don't output anything, but there is no looping or branching (<code>--SkipTo</code> looks like a branch, but it just hides all of the lines until the referenced label. || ScriptCards scripts support true branching, including direct branching (<code>--^</code>) and procedure branching (<code>--></code>) and (<code>--<</code>). Procedures support parameters and a call stack so procedures can be nested to call other procedures.<br />
|-<br />
| All lines in a PowerCards macro need to have unique tags because PowerCards builds the card as a single JavaScript object using the tag names to store what will be displayed. This is why repeated tag names always result in the last one being shown. || ScriptCards tags do not need to be unique, and in the case of many line types are optional.<br />
|-<br />
| PowerCards conditionals result in either showing or hiding the line they are on. || ScriptCards conditionals '''''only''''' support branching as the result of the comparison. This branching can be direct (a GOTO) or procedural (a GOSUB) '''''NOTE: As of version 1.2.0, ScriptCards also supports roll/string variable assignment as a result of conditional evaluation, and later versions introduced code blocks that can be implemented as a result of a conditional'''''<br />
|-<br />
| PowerCards relies on the Roll20 [[Quantum Roll]] server and [[Inline|inline rolls]] for all dice functions || ScriptCards includes its own dice roll parser, and '''''does not support''''' [[Inline|inline rolls]]. '''''Note: As of version 1.2.3, ScriptCards will parse [[Inline|inline rolls]], inserting their final value in the place of the roll in the macro, but they are not part of or parsed by the built-in roll parser'''''<br />
|-<br />
| PowerCards RollIDs (often mistaken for variables) are assigned by analyzing the results of an inline roll, and cannot be referenced in other rolls, so you can't roll a <code>1d4</code> and then roll a <code>1d20</code> and add the <code>1d4</code> result because all of the rolls happen on the chat server before PowerCards gets the macro text. || ScriptCards supports two types of variables: <code>Roll Variables</code> and <code>String Variables</code>. Because ScriptCards uses its own roll parser and is not dependent upon the chat server, rolls and their results can be used in other rolls, math functions, output, etc.<br />
|}<br />
<br />
== Example Scripts ==<br />
<br />
'''''Note: The features available in ScriptCards have changed drastically since these examples were written. While these should still work, there are in many cases better ways to do things using language features introduces after these were constructed. Please see the [https://github.com/kjaegers/ScriptCards/tree/main/ScriptExamples Script Examples] section of the official ScriptCards GitHub repository for more updated script examples.<br />
<br />
Below are some sample scripts that utilize the various statement types in ScriptCards:<br />
<br />
=== Divine Smite ===<br />
<br />
This script will prompt the user for a spell slot level to expend on a divine smite. It will check the target's npc_type to see if it is an Undead or Fiend, which adds an additional d8 to the smite roll.<br />
<br />
[[File:ScriptCards Divine Smite.png|Divine Smite Script Output]]<br />
<br />
<pre><br />
!scriptcard {{<br />
--#title|Divine Smite<br />
--=DiceCount|?{Spell Slot Level?|1|2|3|4|5|6|7|8|9} + 1<br />
--=IsFiendOrUndead|0<br />
--?"@{target|npc_type}" -inc fiend|>IsBoosted<br />
--?"@{target|npc_type}" -inc undead|>IsBoosted<br />
--=TotalDice|[$DiceCount] + [$IsFiendOrUndead]<br />
--=SmiteRoll|[$TotalDice]d8<br />
--#emoteText|@{selected|token_name} smites @{target|token_name}<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
--+Smite|deals [$SmiteRoll] radiant damage.<br />
--X|<br />
<br />
--:IsBoosted|<br />
--=IsFiendOrUndead|1<br />
--<|<br />
}}<br />
</pre><br />
<br />
==== How It Works ====<br />
<br />
The first line sets the "title" card parameter to "Divine Smite".<br />
<br />
Line 2 Shows a query to the user asking for the spell slot level, adds one and stores the value in the "DiceCount" Roll Variable. The query/dropdown is generated by the chat server prior to the script being executed.<br />
<br />
Line 3 defaults the "IsFiendOrUndead" Roll Variable to 0.<br />
<br />
Lines 4 and 5 compare the target's "npc_type" attribute (passed by the chat server as text) to see if they include either "undead" or "fiend". If true, the IsBoosted subroutine will be called. No parameters are passed to this subroutine.<br />
<br />
Line 6 sets the "TotalDice" variable to the base (DiceCount) number plus the IsFiendOrUndead number, which will be a 0 or a 1.<br />
<br />
Line 7 calculates "SmiteRoll" by rolling a number of d8 equal to the "TotalDice" value.<br />
<br />
Lines 8-10 set the parameters for the emote, which appears above the card content. By setting the sourceToken and the targetToken, their icons will appear in the emote surrounding the text describing the action.<br />
<br />
Line 11 is the only line that actually produces output on the card. It results in "Smite deals # radiant damage".<br />
<br />
Line 12 ends the script execution, preventing the script from continuing and running the subroutines out of context.<br />
<br />
Lines 14-16 are the IsBoosted subroutine, starting with the :IsBoosted label. The IsFiendOrUndead variable is set to 1, and a return from subroutine is executed.<br />
<br />
=== Magic Missile ===<br />
<br />
This script demonstrates using a loop and calling a subroutine to fire a number of missiles determine by the spell slot level used to cast the spell.<br />
<br />
[[File:ScriptCards_MagicMissile_Fixed.png|Magic Missile Script Output]]<br />
<br />
<pre><br />
!scriptcard {{ <br />
--#title|Magic Missile<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
--=MissileCount|?{Spell Slot Level?|1|2|3|4|5|6|7|8|9} + 2<br />
--=DisplayCount|1<br />
--=MissileDamage|0<br />
--#leftsub|Slot level ?{Spell Slot Level?}<br />
--#rightsub|Ranged Attack<br />
--#emoteText|Fred uses a level ?{Spell Slot Level?} spell slot to fire [$MissileCount.Total] missiles of magical force!<br />
--:MissileLoop|<br />
-->FireMissile|<br />
--=DisplayCount|[$DisplayCount] + 1<br />
--?[$DisplayCount] -le [$MissileCount]|MissileLoop<br />
--+Total|Total damage is [$MissileDamage]<br />
--X|<br />
<br />
--:FireMissile|<br />
--=ThisMissile|1d4 + 1<br />
--=MissileDamage|[$MissileDamage] + [$ThisMissile]<br />
--+Missile|[$DisplayCount.Total] Hits for [$ThisMissile] [b]force[/b] damage<br />
--<|<br />
}}<br />
</pre><br />
<br />
==== How It Works ====<br />
<br />
Lines 1-3 set the card title, the source token and the target token. Setting these tokens causes their icons/avatars to appear in the Emote section of the card.<br />
<br />
Line 4 asks the user what spell slot level they wish to use to cast magic missile. The number of missiles fired is equal to 2 plus the spell level, and this is stored in the MissileCount variable.<br />
<br />
Line 5 stores a 1 in the DisplayCount variable. This will be used to control the loop to determine the number of missiles fired and the missile number when displaying damage rolls.<br />
<br />
Line 6 initializes MissileDamage to 0<br />
<br />
Line 7 sets the left subtitle to the text "Slot Level #", where # is the spell slot level being used.<br />
<br />
Line 8 sets the right subtitle to the text "Ranged Attack".<br />
<br />
Line 9 sets the emoteText parameter with a description of the action, including the slot level and number of missiles fired.<br />
<br />
Line 10 is a label for the missile firing loop<br />
<br />
Line 11 Calls the "FireMissile" subroutine<br />
<br />
Line 12 increases the DisplayCount variable by 1<br />
<br />
Line 13 Checks to see if there are still missles to fire (DisplayCount <= MissileCount) and if so branches to MissileLoop<br />
<br />
Line 14 Displays the total damage dealt by the spell.<br />
<br />
Line 15 stops execution of the script to prevent out of context execution of the subroutine.<br />
<br />
Lines 76-21 are the FireMissile subroutine, beginning with the FireMissile label. The 1d4+1 is rolled and assigned to "ThisMissile". The result is added to the existing MissileDamage total, and a line for the current missile is displayed with the missile number and the damage for the missile.<br />
<br />
=== Longsword Attack ===<br />
<br />
This script demonstrates a standard 5E D&D melee weapon attack, including detection of misses, fumbles, hits, and critical hits. If installed, alterbars is used to decrement the target's BAR3 value by the damage dealt.<br />
<br />
[[File:ScriptCards Longsword.png|Longsword Script Output]]<br />
<br />
<pre><br />
!scriptcard {{<br />
--#title|Longsword<br />
--#leftsub|Melee Attack<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
--#emoteText|@{selected|token_name} attacks @{target|token_name}<br />
--=TargetAC|@{target|npc_ac}<br />
--?[$TargetAC.Total] -gt 0|DoneWithAC<br />
--=TargetAC|@{target|ac}<br />
--:DoneWithAC|<br />
--=AttackRoll|1d20 + @{selected|strength_mod} [STR] + @{selected|pb} [PROF]<br />
--+Attack|@{selected|token_name} rolls [$AttackRoll] vs AC [$TargetAC].<br />
--?[$AttackRoll.Base] -eq 20|Crit<br />
--?[$AttackRoll.Base] -eq 1|Fumble<br />
--?[$AttackRoll.Total] -ge [$TargetAC.Total]|Hit<br />
--+Miss|The attack missed.<br />
--^Final|<br />
<br />
--:Fumble|<br />
--+Fumble!|The attack went horribly wrong.<br />
--^Final|<br />
<br />
--:Hit|<br />
--=Damage|1d8 + @{selected|strength_mod} [STR]<br />
--+Hit!|The attack hit @{target|token_name} for [$Damage] slashing damage.<br />
--@alter|_target|@{target|token_id} _bar|3 _amount|-[$Damage]<br />
--^Final|<br />
<br />
--:Crit|<br />
--=Damage|1d8 + @{selected|strength_mod} [STR] + 1d8 [CRIT]<br />
--+Critical Hit!|The attack hit @{target|token_name} for [$Damage] slashing damage.<br />
--@alter|_target|@{target|token_id} _bar|3 _amount|-[$Damage]<br />
<br />
--:Final|<br />
}}<br />
</pre><br />
<br />
==== How it Works ====<br />
<br />
In lines 1-5, we set the title, subtitle, and emote text along with the tokens for the emote area.<br />
<br />
Lines 6-9 allow us to determine the AC of the target. On the 5E Roll20 sheet, NPCs armor class is stored in "npc_ac", while PCs armor class is in "ac". First we grab npc_ac and if it is zero, we check AC.<br />
<br />
Line 10 rolls the attack roll, rolling 1d20 and adding the attacker's strength modifier and proficiency bonus<br />
<br />
Line 11 displays the result of the attack roll on the card<br />
<br />
Lines 12-14 determine what kind of result the attack had. If the .Base value of the roll was 20, we branch to "Crit". If it was 1, we branch to "Fumble". If the .Total value of the roll was greater than or equal to the AC that was determined in Lines 6-9, we branch to Hit.<br />
<br />
Assuming we didn't branc anywhere, the result of the attack was a miss, so we display that on line 15 and then branch to "Final"<br />
<br />
This is followed by three branch segments, :Fumble, :Hit, and :Crit. A fumble displays a text message and branches to :Final.<br />
<br />
On a hit or a crit, we roll Damage (adding additional damage dice on a crit). We display a "Hit!" or "Critical Hit!" message and then make an API call to AlterBars, passing it the token id, bar we want to modify (3 in this case), and the amount we want to modify by the Damage value.<br />
<br />
=== Party Health Status ===<br />
<br />
This example calculates the current Hit Points remaining and HP percentage for each character and creates a color-coded display with the current party status.<br />
<br />
[[File:ScriptCards Party Health.png]]<br />
<br />
<pre><br />
!scriptcard {{<br />
--#title|Party Status<br />
--#titleCardBackground|#33CC33<br />
--#oddrowbackground|#bfee90<br />
--#evenrowbackground|#90eebf<br />
-->HealthCheck|@{Quej Grastra|character_id}<br />
-->HealthCheck|@{Brim Cheuto|character_id}<br />
-->HealthCheck|@{Odug Ututees|character_id}<br />
--X|End of card Execution<br />
<br />
--:HealthCheck|<br />
--=HealthPerc|[*[%1%]:hp] / [*[%1%]:hp^] * 100 \ 1<br />
--=HealthColor|000000<br />
--?[$HealthPerc.Total] -gt 50|HealthSkip<br />
--=HealthColor|FF0000<br />
--:HealthSkip|<br />
--+[*[%1%]:character_name]|has [#[$HealthColor.RollText]][*[%1%]:hp] of [*[%1%]:hp^][/#] HP [R]([$HealthPerc.Total]%)[/R]<br />
--<|End of HealthCheck<br />
}}<br />
</pre><br />
<br />
==== How it Works ====<br />
<br />
Lines 1-4, we set the card title, and set the title background and row background colors to shades of green.<br />
<br />
Lines 5-7 make gosub calls the the "HealthCheck" subroutine, passing in the character ID of each of the named characters (these are the names of the characters in my test game)<br />
<br />
Line 8 terminates the script execution.<br />
<br />
The remaining lines of the script are the HealthCheck subroutine, which works like this:<br />
<br />
Line 10 is the subroutine label (:HealthCheck)<br />
<br />
Line 11 uses the character id passed as a parameter and combines it with character attribute lookup *(...) to retrieve the value of "hp" and "hp<nowiki>^</nowiki>" for the character. The <nowiki>^</nowiki> character is used to specify that we want the MAX value for this attribute for the second call. We divide these two numbers and multiple by 100 to get a percentage. Finally, we use integer division by 1 to round the percentage and drop the decimals. The end result gets stored in the HealthPerc roll variable.<br />
<br />
Line 12 defaults to color of the health text to black<br />
<br />
Line 13 check to see if the health percentage is greater than 50. If so, it branches to HealthSkip, preventing the script from executing line 13.<br />
<br />
Line 14 sets the color of the health text to red<br />
<br />
Line 15 is the label that will be branched to from Line 13 to skip the red coloring<br />
<br />
Line 16 again uses character attribute substitution and the passed parameter value to output a display line containing the character name, the colorized health total, and the percentage value. The percentage is right-justified.<br />
<br />
Line 17 returns from the HealthCheck subroutine.<br />
<br />
=== Expanded Magic Missile Script ===<br />
<br />
This is the expanded and enhanced version of the Magic Missile script covered in {{yt|watch?v=u50xvNzS9Zk | this video}}. It includes visual and audio effects, checking and deducting spell slots, and applying damage using either Token-Mod or Alterbars.<br />
<br />
<pre><br />
!scriptcard {{ <br />
--#title|Magic Missile<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
<br />
-->GetAndCheckSlotInformation|<br />
<br />
--=MissileCount|[$SlotLevel] + 2<br />
--=DisplayCount|1<br />
--=MissileDamage|0<br />
--#leftsub|Slot level [$SlotLevel]<br />
--#rightsub|Ranged Attack<br />
--#emoteText|@{selected|character_name} uses a level [$SlotLevel.Total] spell slot to fire [$MissileCount.Total] missiles of magical force!<br />
<br />
--:MissileLoop|<br />
-->FireMissile|<br />
--=DisplayCount|[$DisplayCount] + 1<br />
--?[$DisplayCount] -le [$MissileCount]|MissileLoop<br />
--+Total|Total damage is [$MissileDamage]<br />
-->DeductSpellSlot|<br />
--#rightsub|Level [$SlotLevel] Left: [$SlotsRemaining] <br />
-->PlayEffects|none;burst-smoke;beam-magic;spell_01<br />
-->ApplyDamageTokenmod|@{target|token_id};3;-[$MissileDamage]<br />
-->ApplyDamageAlterbars|@{target|token_id};3;-[$MissileDamage]<br />
--X|<br />
<br />
--:FireMissile|<br />
--=ThisMissile|1d4 + 1<br />
--=MissileDamage|[$MissileDamage] + [$ThisMissile]<br />
--+Missile|[$DisplayCount.Total] Hits for [$ThisMissile] [b]force[/b] damage<br />
--<|<br />
<br />
--:GetAndCheckSlotInformation|<br />
--=SlotLevel|?{Spell Slot Level?|1|2|3|4|5|6|7|8|9}<br />
--=SlotsTotal|[*S:lvl[$SlotLevel]_slots_total]<br />
--=SlotsExpended|[*S:lvl[$SlotLevel]_slots_expended]<br />
--?[$SlotsExpended.Total] -ge [$SlotsTotal.Total]|NoSlotsLeft<br />
--<|<br />
<br />
--:NoSlotsLeft|<br />
--+|[*S:character_name] has no level [$SlotLevel.Total] spell slots available.<br />
--X|<br />
<br />
--:DeductSpellSlot|<br />
--=SlotsExpended|[$SlotsExpended] + 1<br />
--@setattr|_charid [*S:character_id] _lvl[$SlotLevel]_slots_expended|[$SlotsExpended] _silent<br />
--=SlotsRemaining|[$SlotsTotal] - [$SlotsExpended]<br />
--<|<br />
<br />
--:PlayEffects|Parameters are : source effect; target effect; line effect; sound effect<br />
--vtoken|@{selected|token_id} [%1%]<br />
--vtoken|@{target|token_id} [%2%]<br />
--vbetweentokens|@{selected|token_id} @{target|token_id} [%3%]<br />
--@roll20AM|_audio,play,nomenu|[%4%]<br />
--<|<br />
<br />
--:ApplyDamageTokenmod|Parameters are tokenid;bar#;amount<br />
--@token-mod|_ignore-selected _ids [%1%] _set bar[%2%]_value|[%3%]<br />
--<|<br />
<br />
--:ApplyDamageAlterbars|<br />
--@alter|_target|[%1%] _bar|[%2%] _amount|[%3%]<br />
--<|<br />
}}<br />
</pre><br />
<br />
===Hidden Roll===<br />
<br />
A roll where only the GM sees the result of the roll.<br />
[[File:Scriptcards-hiddenroll.png|right]]<br />
<pre><br />
!script {{<br />
--#title|Stealth Check<br />
--=Roll|1d20 + @{selected|stealth}<br />
--+|@{selected|token_name} attempts to move undetected...<br />
--*GMLine|@{selected|token_name} rolled a [$Roll]<br />
}}<br />
</pre><br />
<br />
===Elsewhere===<br />
* {{fpl|10000297/ Scritpcard API Working and Sharing}}<br />
* [https://gist.github.com/dubzilla1/cba439bd1f47ecdd81d0c79a482c4a91 Pathfinder 2E heal macros]<br />
<br />
[[Category:Featured articles]]</div>5004103https://wiki.roll20.net/Script:ScriptCardsScript:ScriptCards2022-02-10T10:23:08Z<p>5004103: /* Object Modification (--!) */</p>
<hr />
<div>{{revdate}}<br />
== Introduction ==<br />
'''ScriptCards''' provides a script interpreter that can be used to create powerful macros that display the results of player/NPC actions, or display other information in a pleasing visual format in your game's {{Text Chat}}. The scripting language contains variables (both dice-roll (enhanced numerics) and strings) as well, conditionals, branching, subroutines with parameters, and a set of built-in functions to simplify working with Roll20 information.<br />
{{script overview<br />
|name=ScriptCards<br />
|author=[[Kurt J.]]<br />
|code=ScriptCards<br />
|version=1.4.10<br />
|lastmodified=2021-12-04}}<br />
ScriptCards is not game-system specific, and can be used with any system/sheet. Near the end of this Wiki there is a section set aside for libraries that can implement system-specific tasks, with the hope that enthusiasts playing particular systems will create and share utility functions that can be utilized by the wider community.<br />
<br />
The default display style for ScriptCards output is similar to the format used to document player and NPC abilities in Dungeons and Dragons 4th Edition, but does not have any system ties to D&D4E.<br />
<br />
Current OneClick Version : 1.4.10<br />
'''''Note:''''' '''As of 2021-12-04, ScriptCards 1.4.10 has been submitted for OneClick update. The documentation below is in the process of being updated for 1.4.10.<br />
<br />
Current Development Version : 1.5.2<br />
<br />
'''''<big>Critically Important: ScriptCards does not use/parse [[Inline|inline rolls]]. ScriptCards includes its own built-in dice roll parser to allow for the use of variables inside dice rolls. As of version 1.2.3, ScriptCards will now take inline rolls and substitute the total result value in statement strings, meaning that you can utilize inline rolls but ScriptCards will only see the result of the roll, and not parse the roll components itself.</big>'''''<br />
{{#evp:youtube|hyR7Jnq4mQM|[[Script:ScriptCards|ScriptCards]] Introduction|right|650}}<br />
* {{fpl|9752053/ ScriptCards thread}}<br />
** {{fpl|10000297/ Scritpcard API Working and Sharing}}<br />
* {{repo|kjaegers/ScriptCards/tree/main/ScriptCards_API ScriptCards_API}} - GitHub repository for source before the one-click version is updated.<br />
* {{repo|kjaegers/ScriptCards/tree/main/ScriptExamples ScriptCards Samples}} - Branch of the GitHub repo that contains sample scripts.<br />
* {{yt.be|hyR7Jnq4mQM ScriptCards Intro}} 45min, Jan 2021<br />
* {{yt.be|u50xvNzS9Zk ScriptCards Magic Missile Deep Dive}} 39min, Feb 2021<br />
__TOC__<br />
=== Is ScriptCards Related to [[PowerCards]]? ===<br />
<br />
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.<br />
<br />
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 ({{code|name}}, {{code|leftsub}}, {{code|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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
Check the '''[[#What to Know if you are Coming from PowerCards|What to Know if you are Coming from PowerCards]]'''-section for a comparison table between the two scripts.<br />
<br />
=== What is a ScriptCard Script ===<br />
<br />
A ScriptCard Script is text written into the {{Text Chat}} (either typed directly, pasted, or run via a macro) that will produce a card of information in the [[Text Chat|chat window]]. A ScriptCard Script is composed of an [[API]] command: <code><nowiki>!scriptcard {{ }}</nowiki></code> enclosing any number of lines that determine the output that will be added to the card. At it simplest, the following macro:<br />
<br />
<pre>!scriptcard {{ }}</pre><br />
<br />
Will produce just a title card that displays “ScriptCards” as the name:<br />
<br />
[[File:Scriptcard blank.png]]<br />
<br />
Of course, this is just the simplest type of macro and isn’t very useful. In order to produce useful output, we need to include lines between the <code><nowiki>{{</nowiki></code> and <code><nowiki>}}</nowiki></code> that direct the API script as to what it should do.<br />
<br />
== Structure of a ScriptCard Line ==<br />
<br />
All ScriptCard lines begin with two dashes, followed by an ''statement identifier character'' that lets ScriptCards what type of line it is. There are several of these, and they are detailed in the next section. After the line type identifier, a Tag name 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.<br />
<br />
Following the Tag is a vertical bar, and then the content of the line itself. Again, each type of line might interpret this content differently.<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Identifier !! Statement Type !! Tag !! Content !! Notes<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--/</nowiki> || Comment || unused || unused || The <code>--/</code> 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--#</nowiki> || 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").<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--+</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--=</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--&</nowiki> || Assign String 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. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--@</nowiki> || 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 (i.e., [[TokenMod|!token-mod]], or [[ChatSetAttr|!setattr]], etc.)<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--:</nowiki> || 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<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--^</nowiki> || Branch To || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--></nowiki> || Call Procedure || 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<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--<</nowiki> || 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.<br />
|- <br />
| style="white-space:nowrap" | <nowiki>--?</nowiki> || Conditional Branch || Condition to be evaluated || True Branch Label<nowiki>|</nowiki>False Branch Label || The condition will be evaluated and execution will jump to one of the two indicated branches (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 included a semicolon separated list of parameters. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--s</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--l</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--v</nowiki> || 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+'''''<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--a</nowiki> || Play Audio Track || Unused || Jukebox track name (case sensitive) || Plays an audio track by name from the Roll20 jukebox. '''''Requires v1.5.2+'''''<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--e</nowiki> || Echo to Chat || Name to send chat command as || Chat message to send || Variable substitution takes place on the tag and content.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--R</nowiki> || Retrieve Repeating Section Row information || "find", "first", or "next" || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--~</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--c</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--i</nowiki> || Information Request || User Prompt;Button Caption || InfoType;VariableName;ParameterText || See full documentation below.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--d</nowiki> || 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. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--%</nowiki> || 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. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--*</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--!</nowiki> || Object Modification || <objectType>:<objectId> || setting:value|setting:value|setting:value... || Set properties of tokens/characters or character attributes ('''''v1.5.0+ required''''')<br />
|}<br />
<br />
== ScriptCard Statement Type Details ==<br />
The sections below detail the individual statement types supported by ScriptCards<br />
<br />
=== Comment (--/) ===<br />
<br />
A --/ statement is ignored by the ScriptCards parser. You can use this type of statement to add comments and informational text to your script. <br />
<br />
Example:<br />
<pre><br />
!script {{<br />
--/|Script Name : Fireball<br />
--/|Purpose : Allow the player to cast a fireball and blow stuff up!<br />
.<br />
.<br />
.<br />
}}<br />
</pre><br />
<br />
=== Set Parameter (--#) ===<br />
<br />
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.<br />
<br />
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.<br />
<br />
'''''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.'''''<br />
<br />
Examples:<br />
<pre><br />
--#title|Magic Missile<br />
--#leftsub|Level 1 Spell<br />
--#rightsub|Force Damage<br />
</pre><br />
<br />
The three examples above set the “title”, “leftsub”, and “rightsub” values for the card to the content value for the line. <br />
<br />
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.<br />
Settings Lines do not produce output lines on the card.<br />
<br />
The following settings are available (note that parameter names are ''not'' case sensitive):<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Name !! Effect/Use !! Default Value !! Type<br />
|-<br />
| 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<br />
|-<br />
| allowplaintextinrolls || If set to a non-zero value, plain character text in rolls will be copied to the roll text || 0 || Per-Line<br />
|-<br />
| bodyFontFace || Name of the font used in the card rows || Helvetica || Global<br />
|-<br />
| bodyFontSize || Size of the text in the card rows || 14px || Global<br />
|-<br />
| bodybackgroundimage || Specify an image (content for a CSS background-image tag) for the body area || none || Global<br />
|-<br />
| buttonBackground || Background color for buttons created with [button][/button] || #1C6EA4 || Per-Line<br />
|-<br />
| buttonBackgroundImage || A CSS specifier for a background image to use for buttons (i.e. url(...);) || empty || Per-Line<br />
|-<br />
| buttonBorderColor || Border (outline) color for buttons created with [button][/button] || #999999 || Per-Line<br />
|-<br />
| buttonFontFace || Font Family specifier for captions on buttons created with [button][/button] || Tahoma || Per-Line<br />
|-<br />
| buttonFontSize|| Text size for captions on buttons created with [button][/button] || x-small || Per-Line<br />
|-<br />
| buttonTextColor|| Text color of labels on buttons created with [button][/button] || #FFFFFF || Per-Line<br />
|-<br />
| 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<br />
|-<br />
| deferralcharacter || Changes the meta script deferral sequence to the specified value || ^ || Per-Line<br />
|-<br />
| diceFontColor|| Color of the dice created with the [d4] [d6], etc. formatting markers || #1C6EA4 || Per-Line<br />
|-<br />
| dicefontsize || Size of the dice created with the [d4] [d6], etc. formatting markers || 3.0em || Per-Line<br />
|-<br />
| 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<br />
|-<br />
| disablerollprocessing || If set to a non-zero value, --= lines will not process dice rolls strings || 0 || Per-Line<br />
|-<br />
| emoteBackground || Background color of the emote area || #f5f5ba || Global<br />
|-<br />
| emoteFont || Name of the font used in emote area (above the title of the output card) || Georgia || Global<br />
|-<br />
| emoteFontColor || Color of the font in the emote area || None (Empty) || Global<br />
|-<br />
| emoteFontSize || Size of the font used in the emote area || 14px || Global<br />
|-<br />
| emoteFontWeight || Font weight for the font in the emote area || bold|| Global<br />
|-<br />
| emoteState || If set to anything other than "visible", the emote portion of the card will not be displayed || visible || Global<br />
|-<br />
| emoteText || Text to display in the emote portion of the card || None (Empty) || Global<br />
|-<br />
| emotefont || Name of the font used in the emote text area || font-family: Georgia, serif; font-weight: bold; || Global<br />
|-<br />
| evenRowBackground || Hex code for the background color for even rows || #eeeeee || Per-Line<br />
|-<br />
| evenRowFontColor || Hex code for the text color for even rows || #000000 || Per-Line<br />
|-<br />
| evenrowbackgroundimage || Specify an image (content for a CSS background-image tag) for the even card rows || none || Per-Line<br />
|-<br />
| executionlimit || Maximum number of script lines the interpreter will try to execute. This prevents "infinite loop" sandbox crashes || 40000 || Global<br />
|-<br />
| hideCard || If set to any non-default value, the entire card output will be suppressed || 0 || Global<br />
|-<br />
| 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<br />
|-<br />
| 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<br />
|-<br />
| lineheight || Vertical size of each line on the output card || normal || Per-Line<br />
|-<br />
| nominmaxhighlight || If set to anything other than "0", rolls will not display crit/fumble/mixed highlight colors. || 0 || Per-Line<br />
|-<br />
| norollhighlight || If set to anything other than "0", rolls will not be formatted (plain numbers) but will still get a tooltip with details ('''''v1.3.6b+''''') || 0 || Per-Line<br />
|-<br />
| oddRowBackground || Hex code for the background color for even rows || #d0e4f5 || Per-Line <br />
|-<br />
| oddRowFontColor || Hex code for the text color for odd rows || #000000 || Per-Line<br />
|-<br />
| oddrowbackgroundimage || Specify an image (content for a CSS background-image tag) for the odd crd rows || none || Per-Line<br />
|-<br />
| reentrant || Used to name a script for rentrant button use || 0 || Global<br />
|-<br />
| 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)0 || Global<br />
|-<br />
| rollhilightcolorboth || Background box hilight color if both a 1 and a max on the die are rolled ('''''1.4.4+''''') || #8FA4D4 || Per-Line<br />
|-<br />
| rollhilightcolorcrit || Background box hilight color if the maximum number on the die was rolled ('''''1.4.4+''''') || #88CC88 || Per-Line<br />
|-<br />
| rollhilightcolorfumble || Background box hilight color if a 1 was rolled ('''''1.4.4+''''') || #FFAAAA || Per-Line<br />
|-<br />
| rollhilightcolornormal || Background box hilight color if neither a 1 or a max on the die are rolled ('''''1.4.4+''''') || #FFFEA2 || Per-Line<br />
|- <br />
| rollhilightlineheight || Determines the height of the hilight box placed around roll results ('''''1.4.2+''''') || 1.0em || Per-Line<br />
|-<br />
| roundUp || If set to a non-default value, integer division will round up instead of down || 0 || Per-Line<br />
|-<br />
| showfromfornonwhispers || If set to a non-zero value, will include the sender on cards that aren't whispered || 0 || Global<br />
|-<br />
| 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<br />
|-<br />
| subtitleFontColor || Color of the text in the subtitle areas || #FFFFFF || Global<br />
|-<br />
| subtitleFontFace || Name of the font used on the subtitle sections || Tahoma || Global<br />
|-<br />
| subtitleFontSize || Size of the subtitle font || 13px || Global<br />
|-<br />
| subtitleSeperator || The character(s) that will be placed between leftsub and rightsub || <nowiki>&#x2666</nowiki>; || Global<br />
|-<br />
| tableBorderRadius || CSS specifier for how rounded the borders of the output card are. Use "0px;" for square borders || 6px; || Global<br />
|-<br />
| tableShadow || CSS specifier for the drop shadow under the output card || 5px 3px 3px 0px #aaa; || Global<br />
|-<br />
| tablebgcolor || Background color of the whole card. '''''Normally not visible''''' || #EEEEEE || Global<br />
|-<br />
| tableborder || Color of the border that surrounds the whole card || 2px solid #000000; || Global<br />
|-<br />
| 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<br />
|-<br />
| timezone || IANA Specifier for the local time zone, used in system/date functions || America/New_York || Per-Line<br />
|-<br />
| title || Text displayed in the title area of the card || ScriptCards || Global<br />
|-<br />
| titleCardBackground || A hex color code representing the background color of the title area. || #1c6ea4 || Global<br />
|-<br />
| titleFontColor || Color of the text on the card title || #FFFFFF || Global<br />
|-<br />
| titleFontFace || Name of the font used on the title area || Contrail One || Global<br />
|-<br />
| titleFontLineHeight || Line spacing on the title area || 1.2em || Global<br />
|-<br />
| titleFontSize || Size of the title font || 1.2em || Global<br />
|-<br />
| titlecardbackgroundimage || Specify an image (content for a CSS background-image tag) for the title card area || none || Global<br />
|-<br />
| titlecardbottomborder || Border CSS specifier for the bottom of the title card area || 2px solid #444444; || Global<br />
|-<br />
| titlecardgradient || If set to non-zero value, will place a vertical gradient on the title card area || 0 || Global<br />
|-<br />
| usehollowdice || If set to a non-zero value, the hollow/outline versions of the dice fonts will be used || 0 || Per-Line<br />
|-<br />
| whisper|| Comma separated list of who to whisper the output to. Use "gm" for [[GM|GMs]] and "self" for the sender || none || Global|}<br />
|}<br />
<br />
''Setting Lines do not produce output lines on the card''<br />
<br />
=== Direct Output (--+) ===<br />
<br />
A direct output line display 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.<br />
<br />
Examples of Direct Output lines:<br />
<pre><br />
--+Hello|World<br />
--+Attack|The monster rolls [$Attack] to hit!<br />
--+Damage|@{target|token_name} is hit for [$Damage] [#3333AA][b]frost[/b][/#] damage.<br />
</pre><br />
<br />
Direct Output lines support inline formatting, roll variable replacement, character attribute references, and procedure variables.<br />
<br />
=== GM Output (--*) ===<br />
<br />
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. <br />
<br />
Example:<br />
<pre><br />
--+PlayerLine|This line is shown on the public card<br />
--*GMLine|This line will only be shown to GMs, on a separate card.<br />
</pre><br />
<br />
=== Roll Variable Assignment (--=) ===<br />
<br />
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.<br />
<br />
'''''All components of a roll equation should be separated with spaces.'''''<br />
<br />
Examples:<br />
<pre><br />
--=MissileDamage|1d4 + 1<br />
--=Attack|1d20 + @{selected|strength_mod} [STR] + @{selected|pb} [PROF]<br />
</pre><br />
<br />
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. Text enclosed in square brackets ([]) is considered "flavor text" and will be added to the result text but does not impact the roll result.<br />
<br />
The following dice formats are supported:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Format Pattern !! Example !! Description<br />
|-<br />
| XdY || 3d8 || Simple format. Roll a Y-sided die X times<br />
|-<br />
| XdYkhZ || 2d20kh1 || Roll Y-sided die X times and keep the highest Z number of dice<br />
|-<br />
| XdYklZ || 4d6kl3 || Roll Y-sided die X times and keep the lowest Z number of dice <br />
|-<br />
| XdY>Z || 5d6>3 || Roll Y-sided die X times and count a 1 for each roll greater than Z <br />
|-<br />
| XdY<Z || 5d6<3 || Roll Y-sided die X times and count a 1 for each roll less than Z <br />
|-<br />
| 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<br />
|-<br />
| 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<br />
|-<br />
| 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)<br />
|-<br />
| 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<br />
|-<br />
| 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).<br />
|-<br />
| 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.<br />
|-<br />
| 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. ('''''v1.5.1''''')<br />
|}<br />
<br />
The following operators are supported in a roll equation:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Operator !! Operation<br />
|-<br />
| + || Addition <br />
|-<br />
| - || Subtraction <br />
|-<br />
| * || Multiplication <br />
|-<br />
| / || Division <br />
|-<br />
| \ || Integer Division (Rounds down) <br />
|-<br />
| % || Modulo (Remainder of Divison)<br />
|}<br />
<br />
Roll Variables can be accessed at any time after they have been created by using the [$VariableName] format, with the following optional modifiers:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Modifier !! Meaning<br />
|-<br />
| No modifier || In a Direct Output Line (<nowiki>--+</nowiki>) 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<br />
|-<br />
| .Total || The end result of the roll equation as an unformatted number <br />
|-<br />
| .Base || The cumulative result of any dice rolled in the Roll Text (Numeric modifiers are not included) <br />
|-<br />
| .Ones || The number of dice in the roll that came up as 1s <br />
|-<br />
| .Aces || The number of dice in the roll that came up as the maximum number on the die <br />
|-<br />
| .Odds || The number of dice in the roll that came up with an odd number <br />
|-<br />
| .Evens || The number of dice in the roll that came up with an even number <br />
|-<br />
| .RollText || The raw text of the roll that was use to generate the results <br />
|-<br />
| .Text || A text representation of the results of the roll, including the numbers rolled for each die <br />
|-<br />
| .tableEntryText || The text portion of the result of a table roll<br />
|-<br />
| .tableEntryImgURL || The image source portion of the result of a table roll<br />
|-<br />
| .tableEntryValue || Numeric value of tableEntryText (via parseInt). If a non-numeric value, will be 0<br />
|-<br />
| .Raw || The total numeric result without any formatting, even if placed somewhere formatting would normally be done. <br />
|}<br />
<br />
Examples:<br />
<pre><br />
--+Total Damage|[$MissileDamage.Total] (roll was 1d4+1)<br />
--+Base Damage|[$MissileDamage.Base] (without the +1)<br />
--=Attack|1d20 + @{selected|strength_mod} [STR] + @{selected|pb} [PROF] + [$BlessBonus] [Bless]<br />
</pre><br />
<br />
In this case, 1d4 will be rolled and stored in “BlessBonus”, which can then be used in the Attack line.<br />
<br />
'''''Mathematical Functions in Roll Expressions '''''<br />
<br />
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:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Expression !! Meaning<br />
|-<br />
| {ABS} || Absolute Value<br />
|-<br />
| {CEIL} || Ceiling value (round up to the next whole number)<br />
|-<br />
| {FLOOR} || Floor value (round down to the next whole number)<br />
|-<br />
| {ROUND} || Round value (round up if the decimal portion is greater than 0.5, otherwise round down) '''Note: As of 1.4.11, ROUND now supports :X as a suffix to round to a given number of decimal places (ie, {ROUND:2}'''<br />
|-<br />
| {NEGATE} || Multiply the value by negative one.<br />
|-<br />
| {SQRT} || Take the square root of the running value.<br />
|-<br />
| {SQUARE} || Square the running value.<br />
|-<br />
| {CUBEROOT} || Take the cube root of the running value.<br />
|-<br />
| {CUBE} || Cube the running value.<br />
|-<br />
| {SIN} || Return the SIN of running value.<br />
|-<br />
| {COS} || Return the COS of running value.<br />
|-<br />
| {TAN} || Return the TAN of running value.<br />
|-<br />
| {ASIN} || Return the ASIN of running value.<br />
|-<br />
| {ACOS} || Return the ACOS of running value.<br />
|-<br />
| {ATAN} || Return the ATAN of running value.<br />
|-<br />
| {MAX:X} || Caps the running value at X. ('''''v1.4.12''''')<br />
|-<br />
| {MIN:X} || If the running value is less than X, set the value to X. ('''''v1.4.12''''')<br />
|-<br />
| {CLAMP:X:Y} || Adjust the running value to remain between X (lower bound) and Y (upper bound) ('''''v1.4.12''''')<br />
|}<br />
<br />
Here are the syntax rules when using the above listed functions:<br />
<br />
Example 1.<br />
<br />
<pre><br />
!script {{<br />
--=output|2.9 {FLOOR}<br />
--+output|[$output]<br />
}}<br />
</pre><br />
<br />
The output from this example is "2".<br />
<br />
Example 2.<br />
<br />
<pre><br />
!script {{<br />
--=output|2.9 {FLOOR} {NEGATE} - 3<br />
--+output|[$output]<br />
}}<br />
</pre><br />
<br />
The output from this example is "-5".<br />
<br />
Basically, a function will use as its input whatever the current "running total" is.<br />
<br />
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.<br />
<br />
<br />
'''''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 <nowiki>[[ ]]</nowiki> 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.<br />
<br />
'''''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.<br />
<br />
'''Rolling on Rollable Tables'''<br />
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.<br />
<br />
''Roll Variable Lines do not produce output lines on the card.''<br />
<br />
=== String Variable Assignment (--&) ===<br />
<br />
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:<br />
<br />
<pre><br />
--&MyText|Hello<br />
</pre><br />
<br />
Here, we assign the text "Hello" to the string variable named MyText. You can also append text to a string variable by prefixing the content with a + sign:<br />
<br />
<pre><br />
--&MyText|+ World<br />
</pre><br />
<br />
If run after the statement above, MyText will now contain "Hello World".<br />
<br />
String variables can be referenced using the syntax [&variablename]<br />
<br />
=== Call API (--@) ===<br />
<br />
ScriptCards can use a Call API instruction to execute other API commands. The Tag contains the API 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 API command is executed.<br />
<br />
Examples:<br />
<pre><br />
--@eh|list<br />
--@alter|_target|@{target|token_id} _bar|3 _amount|-[$Damage]<br />
</pre><br />
<br />
In the first example above, the command <code>!eh list</code> will be executed, calling [[EncounterHelper]]. In the second, {{fpl|1216260/ AlterBars}} is called to modify a token's Bar 3 value.<br />
<br />
'''''Note:''''' When ScriptCards (or any API script) runs other API 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).<br />
<br />
See [[API:Script Index]] for more options.<br />
<br />
=== Branch Label (--:) ===<br />
<br />
A branch label defines a line in your code that can be reached by one of the branching instructions (<nowiki>--^</nowiki>, <nowiki>--></nowiki>, or <nowiki>--?</nowiki>). The Tag serves as the label name, and must be unique on the card.<br />
<br />
The vertical bar (|) separator must be present, but the content portion of the line is unused and can be treated as a comment.<br />
<br />
Examples:<br />
<pre><br />
--:MyLoop|<br />
--:CriticalHit|Will jump here if we roll a critical hit!<br />
</pre><br />
<br />
''A Branch Label line does not produce an output line on the card.''<br />
<br />
=== Branch (--^) === <br />
<br />
A Branch line 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.<br />
<br />
Examples:<br />
<pre><br />
--^MyLoop|Jumps to MyLoop<br />
--^SkipCrit|We didn't crit, so skip the Crit code<br />
</pre><br />
<br />
''A Branch line does not produce an output line on the card.''<br />
<br />
=== Call Procedure (-->) ===<br />
<br />
Similar to a branch, a Call Procedure (sometimes knows 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 (<nowiki>--<</nowiki>) 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 (;).<br />
<br />
Examples:<br />
<pre><br />
-->FixFormat|#3333FF;#999999<br />
</pre><br />
<br />
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%].<br />
<br />
=== Return (--<) ===<br />
<br />
A return instruction marks the end of a Gosub procedure. 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.<br />
<br />
Examples:<br />
<pre><br />
--<|<br />
--<|End of MySub<br />
</pre><br />
<br />
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.<br />
<br />
=== Conditional Statement (--?) ===<br />
<br />
A conditional statement contains some equation in the Tag that will be evaluated. '''''If any part of the comparison can/does contain a space, it needs to be surrounded by double quotes'''''<br />
<br />
Based on the true/false result of the evaluation, one of two execution paths will be taken. These execution paths are detailed in the content section of the statement. The "if true" path is specified first (directly after the vertical bar), and the "if false" path is specified after it, also separated by a vertical bar.<br />
<br />
Example:<br />
<pre><br />
--?[$AttackRoll.Total] -ge [$TargetAC]|Hit|Miss<br />
</pre><br />
<br />
'''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.'''<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Branch Format !! Meaning<br />
|-<br />
| Label || If just a label is specified, execution will branch to that label when the comparison is matched.<br />
|-<br />
| >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 <br />
|-<br />
| =VariableName || The roll variable "VariableName" will be assigned the value following a semicolon (ex: --?1 -eq 1|=Roll;1d20)<br />
|-<br />
| &VariableName || The string variable "VariableName" will be assigned the value following a semicolon (ex: --?1 -eq 1|&Result;Hit|&Result;Miss)<br />
|-<br />
| % or %! || The current for...next loop will perform the "next" action (%) or will break out (%!) <br />
|-<br />
| [ || Code block (see below)<br />
|}<br />
<br />
Examples:<br />
<pre><br />
--?[$AttackRoll.Base] -eq 20|CriticalHit<br />
--?[$AttackRoll.Base] -eq 1|>Fumble;@{selected|dexterity_mod}<br />
--?"@{target|npc_type}" -inc "undead"|&MonsterType;Undead|&MonsterType;Not Undead<br />
--?[$Attack.Total] >= [$ArmorClass]|>Hit|>Miss<br />
</pre><br />
<br />
In the first example, if the Base value of AttackRoll is a 20 (natural 20 on the die) execution will branch to the CriticalHit label.<br />
<br />
In the second example, 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%].<br />
<br />
The third example looks for the word "undead" in the npc_type attribute of the targeted character. If it exists in the text, the MonsterType string variable will be set to "Undead", otherwise it will be set to "Not Undead". <br />
<br />
The final example would call 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.<br />
<br />
''Text that does/may contain a space should be enclosed in double quotes.''<br />
<br />
The following comparison operators are available:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Comparator !! Meaning<br />
|-<br />
| -eq || Equal To <br />
|-<br />
| -eqi || Case insensitive Equal To <br />
|-<br />
| -ne || Not Equal To <br />
|-<br />
| -nei || Case insensitive Not Equal To <br />
|-<br />
| -gt || Greater Than <br />
|-<br />
| -ge || Greater Than or Equal To <br />
|-<br />
| -lt || Less Than <br />
|-<br />
| -le || Less Than or Equal To <br />
|-<br />
| -inc || Includes (text strings). <br />
|-<br />
| -ninc || Does Not Include (text strings). <br />
|}<br />
<br />
Multi-part conditionals are supported with -and and -or as separators. For example:<br />
<br />
<pre><br />
--?[$Attack.Total] -ge @{target|npc_ac} -and [$Attack.Base] -ne 20|HitButNotCrit<br />
</pre><br />
<br />
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):<br />
<br />
true AND false OR true<br />
<br />
Will be evaluated as true. The first two (true and false) will be false, but then false OR true will be true.<br />
<br />
Conversely:<br />
<br />
true or false and false<br />
<br />
Will be false, because the first true and false will evaluate to true, and then true and false will be false.<br />
<br />
'''CODE BLOCKS'''<br />
<br />
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.<br />
<br />
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:<br />
<br />
<pre><br />
!script {{<br />
--=Roll|1d2<br />
--+Roll|[$Roll]<br />
--?[$Roll.Total] -eq 2|[<br />
--&Value|Yep!<br />
--+|We are inside the TRUE portion of the block<br />
--]|[<br />
--&Value|Nope<br />
--+|We are inside the FALSE portion of the block<br />
--]|<br />
--+After|the blocks!<br />
--+Value|[&Value]<br />
}}<br />
</pre><br />
<br />
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 --]|. <br />
<br />
At this time, blocks cannot be nested, and can only be created as part of a conditional (--[ is not a valid statement type)<br />
<br />
''A conditional statement does not produce a line of output on the card.''<br />
<br />
=== Case Statement (--c) ===<br />
<br />
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 (:). Each match condition includes a branch label that will be used if the test value matches the item. 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:<br />
<br />
<pre><br />
!script {{<br />
--#title|Case Statement Testing<br />
--=Roll|1d4<br />
--C[$Roll.Total]|1:>One;[$Roll]|2:>Two;[$Roll]|3:>Three;[$Roll]|4:>Four;[$Roll]<br />
--X|<br />
<br />
--:One| --+Value|was One ([%1%]) --<|<br />
--:Two| --+Value|was Two ([%1%]) --<|<br />
--:Three| --+Value|was Three ([%1%]) --<|<br />
--:Four| --+Value|was Four ([%1%]) --<|<br />
}}<br />
</pre><br />
<br />
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 variable as a parameter.<br />
<br />
=== Save and Load (--s and --l) ===<br />
<br />
This statement pair is used to either store (--s) or load (--l) data from persistent storage. Items stored in persistent storage remain between card rolls and between Roll20 sessions. There are two types of data that can be stored: settings and roll variables. <br />
<br />
Examples:<br />
<br />
<pre><br />
--Ssettings|GreenStyle<br />
--Srollvariables|FirstCardVars<br />
</pre><br />
<br />
In this case, the tag for the statement determines what type of item is being saved (settings or rollvariables). When saving settings, all non-default settings are written to the named setting storage value. When Roll Variables are saved, all variables that currently exist will be saved to the named storage value.<br />
<br />
Loading stored items simply requires the same command with the --l statement type:<br />
<br />
<pre><br />
--Lsettings|GreenStyle<br />
--Lrollvariables|FirstCardVars<br />
</pre><br />
<br />
When loading settings, all stored settings will be applied to the current card settings. You can override settings by changing them after the load.<br />
<br />
When loading roll variables, the saved variables will be added to (or overwrite if they have the same name) any variables on the current card. This means it is safe to create roll variables before the load statement.<br />
<br />
'''Practical Uses'''<br />
The major intended use of persistent storage is for storing card formats for use in later scripts. For example, the following script:<br />
<br />
<pre><br />
!scriptcard {{<br />
--#titlecardbackground|#22CC22<br />
--#oddrowbackground|#cceecc<br />
--#evenrowbackground|#99ee99<br />
--Ssettings|@{selected|token_name}<br />
}}<br />
</pre><br />
<br />
Would save the titlecardbackground, oddrowbackground, and evenrowbackground settings to a saved list named after the selected token's name. When creating cards for that token to run later, you could include the line:<br />
<br />
<pre><br />
--Lsettings|@{selected|token_name}<br />
</pre><br />
<br />
To load all of the settings at once. By creating these setting sets for each character, you can specify a different color scheme for each character that can then be used in cards with a single formatting line.<br />
<br />
There is a supplemental ! command added to support saved settings:<br />
<br />
<pre><br />
!sc-liststoredsettings<br />
</pre><br />
<br />
Will produce a list of all stored setting names, with buttons to list the setting values stored in each group and a button to delete groups as needed.<br />
<br />
=== Visual Effects (--v) ===<br />
<br />
The --v statement can be used to create visual effects on the tabletop. The tag portion of the statement can be either "token" or "betweentokens". The content portion of the statement contains the required parameters for the effect generation, separated by spaces. If the effect is "none", no effect will be played. If any other value that doesn't match a Roll20 effect name will result in a burst-fire effect.<br />
<br />
For "token" effects, the parameters are the token id for the token the effect happens on, followed by the effect specifier.<br />
<br />
Example:<br />
<pre><br />
--vtoken|@{selected|token_id} burst-fire<br />
</pre><br />
<br />
For "betweentoken" effects, the parameters are the source token id, the target token id, and the effect specifier.<br />
<br />
Example:<br />
<pre><br />
--vbetweentokens|@{selected|token_id} @{target|token_id} beam-magic<br />
</pre><br />
<br />
'''''Version 1.2.8+'''''<br />
<br />
An additional effect specifier, "point" is available in 1.2.8+. This specifier allows you to create a visual effect at a designated X/Y pixel coordinate. Future updates will add custom-vfx support to this option. The parameters are the X and Y coordinates and the effect descriptor. As of version 1.2.9, you can also use custom effect specifiers with Point effects:<br />
<br />
<pre><br />
--vpoint|150 200 burst-fire<br />
</pre><br />
<br />
=== Audio Effects (--a) ===<br />
<br />
'''''Requires version 1.5.2+'''''<br />
<br />
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.<br />
<br />
<pre><br />
--a|SwordHitSound<br />
</pre><br />
<br />
No external APIs are required.<br />
<br />
=== Echo to Chat (--e) ===<br />
<br />
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.<br />
<br />
Example:<br />
<pre><br />
--eThe Ghost|/em hovers around @{selected|character_name}... BOO!<br />
</pre><br />
<br />
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).<br />
<br />
'''''Whispering'''''<br />
<br />
You can use the echo statement to send a whisper, but there's a trick to it. If you execute this code here:<br />
<br />
<pre><br />
--eThe Ghost|/w ExamplePlayerName Boo.<br />
</pre><br />
<br />
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.<br />
<br />
So, in conclusion, it's best to use something like this when you're sending a whisper:<br />
<br />
<pre><br />
!script {{<br />
--#hidecard|1<br />
--&sender|The Ghost<br />
--&receiver|ExamplePlayerName<br />
--&message|Boo.<br />
--e[&sender]|/w [&receiver] [&message]<br />
--eScriptCards|/w gm **Whispered from [&sender] to [&receiver]:** [&message] <br />
}}<br />
</pre><br />
<br />
This will ensure that the message appears in your chat feed as well.<br />
<br />
=== Repeating Section Access (--R) ===<br />
<br />
ScriptCards (as of v0.0.13) supports accessing repeating section rows on a character sheet (for example: the attacks, the items, and the repeating resources) with the --R statement type. <br />
<br />
There are three basic commands you can use with --R, and they are specified by <br />
the tag used:<br />
<br />
<br />
'''''The "find" tag'''''<br />
<br />
An Rfind statement is used to search through a repeating field. Here is the general form of such a statement.<br />
<br />
<pre><br />
--Rfind|characterid;EntryName;SectionPrefix;SearchField<br />
</pre><br />
<br />
This is the most direct way to access a repeating section row. Supplying the character ID, followed by what you are looking for (Greatsword, for example), followed by the character sheet's section prefix (repeating_attack), followed by the field to check what you are searching for (atkname) will load the matching section (if found) into the script parsers memory. For example:<br />
<br />
<pre><br />
--Rfind|@{selected|character_id};Greatsword;repeating_attack;atkname<br />
</pre><br />
<br />
Will look at the character's "repeating_attack" section for an entry with an atkname value equal to "Greatsword". Similarly:<br />
<br />
<pre><br />
--Rfind|@{selected|character_id};Bite;repeating_npcaction;name<br />
</pre><br />
<br />
Will look for a "Bite" action on an NPC's action list.<br />
<br />
<br />
'''''The "first" tag'''''<br />
<br />
<pre><br />
--Rfirst|characterid;section prefix<br />
</pre><br />
<br />
This form of the --R command will look at all of the entries in the specified repeating section and load the first one into memory:<br />
<br />
<pre><br />
--Rfirst|@{selected|character_id};repeating_attack<br />
</pre><br />
<br />
Would load the character's first "repeating_attack" row into memory.<br />
<br />
<br />
'''''The "next" tag'''''<br />
<br />
<pre><br />
--Rnext|<br />
</pre><br />
<br />
No parameters are required for --Rnext, which loads the next entry in the list that was obtained with "first" into memory.<br />
<br />
<br />
'''''Section prefixes and how to use them'''''<br />
<br />
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 open [[D&D 5E by Roll20|this page]], and search for the phrase "repeating sections".<br />
<br />
<br />
'''''Additional information'''''<br />
<br />
However a row is obtained, it will be parsed to replace any attribute references (ie, @{level}) with the corresponding character attribute.<br />
<br />
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".<br />
<br />
You can reference repeating attribute data using the syntax [*R:attributename] syntax (similar to referencing standard character attributes).<br />
<br />
Here are some examples:<br />
<br />
Display the details of the "Greatsword" PC attack:<br />
<br />
<pre><br />
!script {{<br />
--Rfind|@{selected|character_id};Greatsword;repeating_attack;atkname<br />
--+Attack Name|[*R:atkname]<br />
--+Base Damage|[*R:dmgbase]<br />
}}<br />
</pre><br />
<br />
[[File:Scriptcards repeating greatsword.png|Repeating Greatsword Attack]]<br />
<br />
List all of the actions an NPC can take (just actions, not legendary, etc.)<br />
<br />
<pre><br />
!script {{<br />
--#title|NPC Actions<br />
--#leftsub|@{selected|token_name}<br />
--Rfirst|@{selected|character_id};repeating_npcaction<br />
--:DisplayLoop|<br />
--?"[*R:name]" -eq NoRepeatingAttributeLoaded|Done<br />
--+Action:|[*R:name] [*R:attack_damage] [*R:attack_damagetype]<br />
--?"[*R:attack_damage2]" -eq ""|NoSecondaryDamage<br />
--+ |[*R:attack_damage2] [*R:attack_damagetype2]<br />
--:NoSecondaryDamage|<br />
--Rnext|<br />
-->DisplayLoop| <br />
--:Done|<br />
}}<br />
</pre><br />
<br />
[[File:Scriptcards repeating npcactions.png]]<br />
<br />
In the script above, we get the "first" repeating_npcaction and display information about it. We then execute "next" and repeat until we run into "NoRepeatingAttributeLoaded".<br />
<br />
See the section named [[#Repeating Section Values|Repeating Section Values]] for more information.<br />
<br />
<br />
'''''Special debugging command: dump'''''<br />
<pre><br />
--Rdump|<br />
</pre><br />
<br />
The "dump" command will list all of the attributes ScriptCards knows about for the currently loaded repeating row to the API Console Log.<br />
<br />
=== Assign Variable to Built-In Function (--~) ===<br />
<br />
ScriptCards has the ability to run a function built into the API script and return the results to a variable. Some functions return roll variables, while others return strings. See the function table below for details. The format is:<br />
<br />
--~VariableName|function;param1;param2;param3;...<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Function Name !! Parameters !! Description<br />
|-<br />
| distance || token_A_ID;token_B_ID || Calculate the Chebyshev distance in grid units between two tokens. This is the measurement scheme D&D 4E/5E use for diagonal distance measurement<br />
|-<br />
| euclideandistance || token_A_ID;token_B_ID || Calculate the Euclidean distance between two tokens. This is essentially the Pythagorean theorem in action. Returns the result in grid units.<br />
|-<br />
| euclideanpixel || token_A_ID;token_B_ID || Calculate the Euclidean distance between two tokens and returns the result is pixels instead of grid units. <br />
|-<br />
| euclideanlong || token_A_ID;token_B_ID || 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 is calculated instead of before. More accurate over long distances. <br />
|-<br />
| manhattandistance || token_A_ID;token_B_ID || Also called "taxicabdistance" (which is an acceptable function name), this measures to how-many-over, how-many-up/down distance, disallowing diagonal movement.<br />
|-<br />
| getselected || none || 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 the first selected token, VariableName2 the second, etc.<br />
|}<br />
<br />
'''''Functions with Sub Functions'''''<br />
<br />
Most ScriptCards functions are grouped into set as sub functions. The table below lists the major functions and their sub functions.<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Function Name !! Sub Function !! Parameters !! Return Type !! Description<br />
|-<br />
| array || define || arrayname;value1;value2;... || none || Creates an array called "arrayname" and adds value1, value2, etc. to the array<br />
|-<br />
| array || sort || arrayname || none || Sorts the specified array in place in ascending order (alphabetically)<br />
|-<br />
| array || numericsort || arrayname || none || Sorts the specified array in place in ascending order (numerically) ('''''v 1.4.10+ ''''')<br />
|-<br />
| array || add || arrayname;value1;value2;... || none || Adds value1, value2, ... to the existing array "arrayname"<br />
|-<br />
| array || remove || arrayname;value1;value2;... || none || Removes value1, value2, ... from the existing array "arrayname". Resets the array index to 0.<br />
|-<br />
| array || replace || arrayname;currentvalue;newvalue || none || Replaces all occurrences of "currentvalue" in "arayname" with "newvalue"<br />
|-<br />
| array || setatindex || arrayname;index;newvalue || none || Replaces the array item at index "index" with "newvalue"<br />
|-<br />
| array || getindex || arrayname || stringVariable || Retrieves the current index in "arrayname" and stores it in the supplied string variable<br />
|-<br />
| array || setindex || arrayname;newindex || none || Sets the current index in array "arrayname" to "newindex"<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| array || removeat || arrayname;indexposition || none || Removes the item at index "indexposition" from "arrayname". Resets the current array index to 0.<br />
|-<br />
| array || indexof || arrayname;searchvalue || stringVariable || Searches the array "arrayname" for and item with the value of "searchvalue" and, if found, returns the index of the first matching value or "ArrayError" if not found<br />
|-<br />
| array || getlength || arrayname || stringVariable || Returns the number of items in array "arrayname"<br />
|-<br />
| array || pagetokens || arrayname;tokenid;(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. 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.)<br />
|-<br />
| 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.<br />
|-<br />
| array || stringify || arrayname || stringVariable || Returns all of the items in "arrayname" as a string separated by semicolons (;)<br />
|-<br />
| array || fromstring || arrayname || delimiter;string || Creates an array from "string", splitting "string" on "delimiter" to separate the items<br />
|-<br />
| array || statusmarkers|| arrayname;tokenid || none|| Creates an array (arrayname) of the active statusmarkers (sometimes called Token Markers) for the specified tokenid<br />
|-<br />
| math || angle || math;angle;tokenid;tokenid|| rollVariable || Calculates the angle between two tokens and returns the value in degrees<br />
|-<br />
| math || ceil || math;ceil;value || rollVariable || Rounds '''value''' up to the next integer, dropping any decimal portion of the number<br />
|-<br />
| math || clamp || math;clamp;value;lowerBound;upperBound || rollVariable || Returns '''value''', but restricted to the range of '''loweBound''' and '''upperBound'''.<br />
|-<br />
| math || floor || math;floor;value || rollVariable || Rounds '''value''' down, dropping any decimal portion of the number<br />
|-<br />
| math || max || math;max;valueA;valueB || rollVariable || Returns the larger of '''valueA''' vs '''valueB'''<br />
|-<br />
| math || min || math;min;valueA;valueB || rollVariable || Returns the smaller of '''valueA''' vs '''valueB'''<br />
|-<br />
| math || round || math;round;value || rollVariable || Rounds '''value''' to the nearest integer<br />
|-<br />
| string || length || string;length;stringValue || rollVariable || Returns the length of '''stringValue''' in characters<br />
|-<br />
| string || before || string;before;searchText;stringValue || stringVariable || Searches '''stringValue''' for '''searchText''' and returns the portion of '''stringValue''' prior to that text<br />
|-<br />
| string || after || string;after;searchText;stringValue || stringVariable || Searches '''stringValue''' for '''searchText''' and returns the portion of '''stringValue''' after that text<br />
|-<br />
| string || left || string;left;count;stringValue || stringVariable || Returns the leftmost '''count''' characters of '''stringValue'''<br />
|-<br />
| string || right || string;right;count;stringValue || stringVariable || Returns the rightmost '''count''' characters of '''stringValue'''<br />
|-<br />
| string || replace || string;replace;searchText;replaceText;stringValue || stringVariable || Replaces '''searchText''' in '''stringValue''' with '''replaceText''' and returns the resulting string<br />
|-<br />
| string || replaceall || string;replace;searchText;replaceText;stringValue || stringVariable || Replaces all intances of '''searchText''' in '''stringValue''' with '''replaceText''' and returns the resulting string '''''Requires 1.2.9+'''''<br />
|-<br />
| string || trim || string;trim;stringValue || stringVariable || Removes leading and trailing spaces from stringValue and returns the result. <br />
|-<br />
| string || substring || string;substring;start;count;stringValue || stringVariable || Returns '''count''' characters starting at '''start''' from '''stringValue'''<br />
|-<br />
| 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.<br />
|-<br />
| string || tolowercase || string;tolowercase;stringValue || stringVariable || Converts the passed string to lower case and assigns to the passed variable name. <br />
|-<br />
| string || touppercase || string || stringVariable || Converts the passed string to upper case and assigns to the passed variable name. <br />
|-<br />
| 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. <br />
|-<br />
| 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.<br />
|-<br />
| 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'''.<br />
|-<br />
| turnorder || clear || none || none || Clears all entries from the {{Turn Tracker}}/Initiative<br />
|-<br />
| turnorder || addtoken || tokenid;trackervalue || none || Adds the token represented by "tokenid" to the initiative tracker with an initiavie value of "trackervalue"<br />
|-<br />
| turnorder || replacetoken || tokenid;trackervalue || none || Replaces the token represented by "tokenid" in the initiative tracker with an initiavie value of "trackervalue". Will add the token if it doesn't exist in the tracker.<br />
|-<br />
| turnorder || removetoken || tokenid || none || Removes the token represented by "tokenid" from the initiative tracker if it exists<br />
|-<br />
| turnorder || addcustom || textlabel;trackervalue || none || Add a custom text entry to the {{Turn Tracker}}/Initiative named "textlabel" with an initiative value of "trackervalue"<br />
|-<br />
| system || date || getdatetime || stringVariable || Returns the date time in the active timezone (see settings) <br />
|-<br />
| system || date || getdate || stringVariable || Returns the date in the active timezone (see settings) <br />
|-<br />
| system || date || gettime || stringVariable || Returns the time in the active timezone (see settings)<br />
|-<br />
| system || dumpvariables || "rolls", "string", or "array" || none || Dumps all of the defined variables of the indicated type to the console log<br />
|-<br />
| system || findability || system;findability;charactername;abilityname || stringVariable || Returns the object ID of the ability on the indicated character or "AbilityNotFound"<br />
|-<br />
|}<br />
<br />
Examples:<br />
<br />
<pre><br />
--~HowFarAway|distance;@{selected|token_id};@{target|token_id}<br />
</pre><br />
<br />
Returns the distance (Chebyshev) between the selected and target tokens and stores it in "HowFarAway".<br />
<br />
<pre><br />
--SelectedDudes|getselected<br />
</pre><br />
<br />
If 5 tokens were selected, 6 variables would be created: SelectedDudesCount (with a value of 5), SelectedDudes1, SelectedDudes2, SelectedDudes3, SelectedDudes4, SelectedDudes5.<br />
<br />
=== Information Request (--i) ===<br />
<br />
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.<br />
<br />
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.<br />
<br />
After the user has clicked the button and responded to the requests, ScriptCards will resume processing the script from where it left off.<br />
<br />
Here is an example “i” line:<br />
<br />
<pre><br />
--IScriptCards needs additional information to continue;Click to select a target and provide information|t;MyNewTarget;Missile1Target||q;MyNameIs;What is your name?<br />
</pre><br />
<br />
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.<br />
<br />
Supported information request types are “t” for target token, and “q” for query.<br />
<br />
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).<br />
<br />
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:<br />
<br />
<pre><br />
q;UserName;What is your name?|Fred|Bob|Sally|Nancy<br />
</pre><br />
<br />
Would have a dropdown menu with four choices.<br />
<br />
=== Object Modification (--!) ===<br />
<br />
'''''Requires ScriptCards version 1.5.0+'''''<br />
<br />
Object modification support is now available in ScriptCards. As of 1.5.0, you can use the --! command to modify object properties in the game. This may help reduce the reliance on the --@ command to run other API commands to modify token/character values. The biggest benefit of this is that the changes happen as the script is processing, so the new values are available right away. <br />
<br />
The format of the command is:<br />
<pre><br />
--!<objectType>:<objectId>|setting:value|setting:value|setting:value...<br />
</pre><br />
<br />
'''objectType''' can be one of "t" for token, "c" for character, or "a" for character attribute<br />
<br />
'''objectId''' can be a token id or a character id (or "S"/"T" for the Source/Target token/char defined with --#sourcetoken and --#targettoken)<br />
<br />
'''setting''' and '''value''' pairs can be chained in a single statement separated by | to impact more than one property/attribute with a single line<br />
<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
Examples:<br />
<br />
Set the value of bar1_value for the selected token to 5:<br />
<pre> --!t:@{selected|token_id}|bar1_value:5</pre><br />
Add 1 to the bar3_value for the selected token:<br />
<br />
<pre> --!t:@{selected|token_id}|bar3_value:+=1</pre><br />
Set bar2_value to 5 and bar2_max to 10 for the selected token<br />
<br />
<pre> --!t:@{selected|token_id}|bar2_value:5|bar2_max:10</pre><br />
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:<br />
<br />
<pre> --!a:@{selected|token_id}|dndstyling:on|size:enormous|!attitude:epic</pre><br />
Adds 50 to the npc_xp attribute for the character represented by the selected token, displaying the value before and after the update:<br />
<br />
<pre><br />
!script {{<br />
--+XP|[*@{selected|token_id}:npc_xp]<br />
--!a:@{selected|token_id}|npc_xp:+=50<br />
--+XP|[*@{selected|token_id}:npc_xp]<br />
}}<br />
</pre><br />
<br />
Note that asynchronous read/update fields (bio, notes, gmnotes) are not currently supported.<br />
<br />
== Inline Formatting ==<br />
<br />
Inline formatting is processed on Direct Output lines only (--+ lines) and the following inline format markup is available:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Formatting Tags !! Description<br />
|-<br />
| [b]..[/b] || Bold the text between the markers <br />
|-<br />
| [i]..[/i] || Italicize the text between the markers <br />
|-<br />
| [u]..[/u] || Underline the text between the markers <br />
|-<br />
| [s]..[/s] || Strike-Thru the text between the markers <br />
|-<br />
| [c]..[/c] || Center alignment <br />
|-<br />
| [l]..[/l] || Left alignment <br />
|-<br />
| [r]..[/r] || Right alignment <br />
|-<br />
| [j]..[/j] || Full justification alignment <br />
|-<br />
| [#xxx]..[/#] or [#xxxxxx]..[/#] || Use a 3 or 6 digit hex code to colorize the text between the markers <br />
|-<br />
| [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, <code>[img width=128 height=128]</code> )<br />
|-<br />
| [button]caption::action[/button] || Create a button with the label "caption" that performs the action defined by "action". By default, buttons will be colored according the the buttontextcolor and buttonbackground card settings. You can optionally color individual buttons by specifying a text color and a background color as part of the [button] command (ie, [button:#ffffff:#000000] will create a button with white text on a black background. In order to set a background color, the foreground color must be specified.<br />
|-<br />
| [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. By default, buttons will be colored according the the buttontextcolor and buttonbackground card settings. You can optionally color individual buttons by specifying a text color and a background color as part of the [sheetbutton] command (ie, [sheetbutton:#ffffff:#000000] will create a button with white text on a black background. In order to set a background color, the foreground color must be specified.<br />
|-<br />
| [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. By default, buttons will be colored according the the buttontextcolor and buttonbackground card settings. You can optionally color individual buttons by specifying a text color and a background color as part of the [rbutton] command (ie, [rbutton:#ffffff:#000000] will create a button with white text on a black background. In order to set a background color, the foreground color must be specified.<br />
|-<br />
| [t] || Converted to HTML table tag. Text after the "t" will be included inside the tag (width, border, etc)<br />
|-<br />
| [/t] || Converted to HTML close table tag.<br />
|-<br />
| [tr] || Converted to HTML table row tag. Text after the "tr" will be included inside the tag<br />
|-<br />
| [/tr] || Converted to HTML close table row tag.<br />
|-<br />
| [td] || Converted to HTML table cell tag. Text after the "tr" will be included inside the tag<br />
|-<br />
| [/td] || Converted to HTML close table cell tag.<br />
|}<br />
<br />
Code Example<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Formatting Tags !! Description<br />
|-<br />
| <pre>!script {{<br />
--#title|Inline Formatting Examples<br />
--+|This text [b]is bolded[/b]<br />
--+|This text [i]is italicized[/i]<br />
--+|This text [u]is underlined[/u]<br />
--+Alignment|[l]Left[/l]<br />
--+|[c]Center[/c]<br />
--+|[r]Right[/r]<br />
--+|[j]This long bit of text is justified to fit smoothly into the display area for the card with justified wrapping.[/j]<br />
--+Colorized|[#f00]Red[/#] [#0f0]Green[/#] [#00f]Blue[/#]<br />
--+Button|[button]Do Something::DoOnClick[/button]<br />
--+Button Colors|[button:#000:#f00]Red::RedClick[/button] [button:#000:#0f0]Blue::BlueClick[/button] [button:#000:#00f]Blue::BlueClick[/button]<br />
--+Table:|<br />
--+|[t border=2 width=100%][tr][td]Cell1[/td][td]Cell2[/td][/tr][tr][td]Cell3[/td][td]Cell4[/td][/tr][/t]<br />
}}</pre> || [[File:Sc-formatting_example.png]]<br />
|}<br />
<br />
== Variables ==<br />
<br />
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. While it is possible to assign both a string and a roll variable the same name, doing so will likely result in confusion when looking at the script later, so it is not recommended.<br />
<br />
String Variables are assigned with the --& statement and are referenced using [&variableName] notation.<br />
<br />
Roll Variables are assigned with the --= statement, and the assignment value is always processed by the ScriptCards Roll Processor (resolves dice rolls, etc.)<br />
<br />
There are a handful of variables assigned automatically when a ScriptCard is executed. These are all string variables, and are:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Variable !! Value<br />
|-<br />
| SendingPlayerID || Contains the object ID of the player that sent the macro<br />
|-<br />
| SendingPlayerName || Contains the display name of the player<br />
|-<br />
| SendingPlayerColor || Contains the color code associated with the player<br />
|-<br />
| SendingPlayerSpeakingAs || The contents of the "Speaking As" dropdown window<br />
|-<br />
| SendingPlayerIsGM || Contains 1 if the player is a GM, and 0 if the player is NOT a GM<br />
|}<br />
<br />
== Arrays ==<br />
<br />
Arrays are a special type of variable, and are managed by the function (<nowiki>--~</nowiki> command). All of the array function commands follow the same pattern:<br />
<br />
<pre>--~variableName|array;subcommand;arrayname;param1;param2;param3;...</pre><br />
<br />
Not all array commands return anything to "variableName". The function table above will specify the return type of the command if any.<br />
<br />
There are a couple of different ways to create an array:<br />
<br />
The '''define''' array subcommand creates (or recreates) an array and assigns it values - one for each included parameter after the array name. For example:<br />
<br />
<pre>--~|array;define;Fruits;mango;peach;strawberry;apricot;banana;apple</pre><br />
<br />
will create an array called '''Fruits''' with 6 elements in the order listed in the command (mango, peach, etc.)<br />
<br />
You can also use two other subcommands to create arrays based on tokens:<br />
<br />
<pre>--~Count|array;pagetokens;Everybondy;@{selected|token_id}</pre><br />
<br />
and<br />
<br />
<pre>--~Count|array;selectedtokens;Selected</pre><br />
<br />
In both cases, arrays of tokens will be created, and a string variable called "Count" will be set to the number of tokens in the array. The '''pagetokens''' command returns (by default) all of the tokens on the page that contains the token passed as the parameter after the array name. You can filter the tokens that "pagetokens" includes in the array by appending an optional parameter describing the type of token you are looking for:<br />
<br />
<pre>--~Count|array;pagetokens;Everybondy;@{selected|token_id};npc</pre><br />
<br />
Will return only tokens on the page that represent characters that do not have a ''controlledby'' parameter set. The available options are "all" (default), "char", "graphic", "pc", and "npc".<br />
<br />
The '''selectedtokens''' command returns an array with all of the tokens that were selected when the script was called.<br />
<br />
You can also use an arbitrary string to create an array, specifying a delimiter with the '''fromstring''' command:<br />
<br />
<pre><br />
--&names|Fred<br />
--&names|+,Sally<br />
--&names|+,Ted<br />
--&names|+,Joyce<br />
--~|array;fromstring;,;[&names]<br />
</pre><br />
<br />
The above example builds a comma-separated string and then uses "fromstring" to create an array with 4 elements from it, specifying the comma as the delimiter.<br />
<br />
Finally, you can use the '''statusmarkers''' command to create an array with one entry for each active status marker on a specified token:<br />
<br />
<pre>--~|array;statusmarkers;Conditions;@{selected|token_id}</pre><br />
<br />
will create an array with one entry for each status active on the selected token. The array elements will be the internal name of the status (if you are using custom status marker packs, the names will be specified in the marker pack).<br />
<br />
'''Traversing Arrays'''<br />
<br />
Each array keeps track of an internal index position (starting at 0). Several commands let you manage this index:<br />
<br />
*'''getindex''' returns the current index value<br />
*'''setindex''' sets the index to the specified location in the array<br />
*'''getlength''' returns the number of elements in the array<br />
*'''indexof''' returns the index location of the specified element<br />
<br />
Other commands let you retrieve values from the array:<br />
<br />
*'''getfirst''' sets the index to 0 and returns the value at that position<br />
*'''getnext''' advances the index by 1 and returns the new current value<br />
*'''getprevious''' reduces the index by 1 and returns the new current value<br />
*'''getlast''' sets the index to the last elements in the array and returns the new current value<br />
<br />
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.<br />
<br />
'''Manipulating Array Elements'''<br />
<br />
Several array commands deal with inserting, removing, and modifying elements:<br />
<br />
*'''add''' works just like define, except that it takes an existing array and adds elements to it based on the passed parameters<br />
*'''remove''' looks for items matching each passed parameter and removes them from the indicated array if they exist<br />
*'''removeat''' allows you to specify an index location in the array and remove the element at that position<br />
*'''replace''' searches an array for a value and replaces all occurrences of it with a new value (if found)<br />
*'''sort''' sorts the elements in the array in ascending order<br />
*'''strinfigy''' returns a string variable that includes each array element separated by semicolons (;) <br />
<br />
'''Referencing Array Elements'''<br />
<br />
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.<br />
<br />
<pre><br />
!script {{<br />
--~dummy|array;pagetokens;myarray;@{selected|token_id}<br />
--~count|array;getcount;myarray<br />
--+Total:|There are [&count] graphical objects on the page<br />
--~testvar|array;getfirst;myarray<br />
--:loop|<br />
--+Value|[*[&testvar]:character_name]<br />
--~testvar|array;getnext;myarray<br />
--?[&testvar] -ne ArrayError|loop<br />
--+Loop1|Is Done!<br />
}}<br />
</pre><br />
<br />
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:<br />
<br />
<pre><br />
!script {{<br />
--~dummy|array;pagetokens;myarray;@{selected|token_id}<br />
--~count|array;getcount;myarray<br />
--+Total:|There are [&count] graphical objects on the page<br />
--%loopCounter|1;[&count]<br />
--+Value|[*[@myarray([&loopCounter])]:character_name]<br />
--%|<br />
--+Loop|Is Done!<br />
}}<br />
</pre><br />
<br />
This line : <nowiki>--+Value|[*[@myarray([&loopCounter])]:character_name]</nowiki> uses [@arrayName(index)] format (inside a [*characterid:attribute] syntax) to perform the same task as running through the loop with the index.<br />
<br />
(Note: Additional examples are on the way...)<br />
<br />
== For...Next Loops ==<br />
<br />
For...Next loops in ScriptCards are supported with the with the --% statement type. A loop is defined by starting off with:<br />
<br />
<pre><br />
--%LoopCounter|<start>;<end>;[step]<br />
</pre><br />
<br />
The start and end values are required, while the step parameter is optional. If the step is omitted, it will be assumed to be 1. A string variable named after the line tag ("LoopCounter" in the case above) will be created and will hold the current iteration value for the loop. Here is a real example:<br />
<br />
<pre><br />
--%LoopCounter|1;10;1<br />
</pre><br />
<br />
This will begin a loop identified by "LoopCounter" that will start at 1, increasing by 1 each iteration (the step) until it has completed 10 executions.<br />
<br />
The "next" statement is simply <code>--%|</code>, with no tag or parameters. This indicates to ScriptCards that it should increment the counter and go back to the beginning of the loop. Extending the example above:<br />
<br />
<pre><br />
!script {{<br />
--%LoopCounter|1;10;1<br />
--=Roll|1d20<br />
--+Loop|Counter is [&LoopCounter], roll was [$Roll]<br />
--%|<br />
}}<br />
</pre><br />
<br />
The <code>--%!|</code> sequence will break out of the loop, no matter how many iterations are remaining.<br />
<br />
The % and %! character sequences can also be used as part of a 1.2.1+ non-branching conditional to continue or break the loop:<br />
<br />
<pre><br />
--?"X[&RollInto]X" -eq "XX"|%<br />
</pre><br />
<br />
In this example, if the string variable RollInfo is empty, the loop will return to the top and continue with the next iteration, while:<br />
<br />
<pre><br />
--?"X[&RollInto]X" -eq "XX"|%!<br />
</pre><br />
<br />
Would cause the whole loop to end if the condition were true.<br />
<br />
== Referencing ==<br />
<br />
=== Roll Variables===<br />
<br />
Roll Variables can be referenced from the content portion of any line type, and from the tag portion of conditional statements. The referenced value is replaced when the line is executed.<br />
<br />
There are several modifiers that can be used to reference parts of a roll:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Modifier !! Meaning<br />
|-<br />
| No modifier || In a Direct Output Line (<nowiki>--+</nowiki>), GM Output Line (<nowiki>--*</nowiki>), or String Assignement (<nowiki>--&</nowiki>), 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<br />
|-<br />
| .Total || The end result of the roll equation. Formatting rules for "No Modifier" apply based on line type. <br />
|-<br />
| .Raw || The total value of the roll variable without any formatting, no matter what kind of line the reference is used in.<br />
|-<br />
| .Base || The cumulative result of any dice rolled in the Roll Text (Numeric modifiers are not included) <br />
|-<br />
| .Ones || The number of dice in the roll that came up as 1s <br />
|-<br />
| .Aces || The number of dice in the roll that came up as the maximum number on the die <br />
|-<br />
| .Odds || The number of dice in the roll that came up with an odd number <br />
|-<br />
| .Evens || The number of dice in the roll that came up with an even number <br />
|-<br />
| .RollText || The raw text of the roll that was use to generate the results <br />
|-<br />
| .Text || A text representation of the results of the roll, including the numbers rolled for each die <br />
|-<br />
| .tableEntryText || The text portion of the result of a table roll<br />
|-<br />
| .tableEntryImgURL || The image source portion of the result of a table roll<br />
|-<br />
| .tableEntryValue || If the tableEntryText is purely numeric, will contain the numeric value<br />
|}<br />
<br />
=== String Variables ===<br />
<br />
To reference a string variable, use the notation [&variablename]. String variables can be referenced in direct output, roll variable assignment, and string variable assignment statements.<br />
<br />
=== Character/Token Attributes ===<br />
<br />
A character or token attribute can be referenced from content portion of any type of line and is substituted when the line is executed. The general format for referencing a character attribute is [*ID:attribute]. ID can be a token ID or a character ID (these start with a dash). Additionally if you have specified a sourceToken or targetToken, you can substitute "S" or "T" for the ID (for example [*S:npc_type] will retrieve the npc_type attribute from the source token.<br />
<br />
By default, all attribute references will be pulled from the '''''character''''' object that the ID represents (either directly or by being a Token ID that represents a character).<br />
<br />
Keep in mind, that if you want to access the "max" of a character attribute (for example, the max hit points), then you cannot trust the name that your roll20 character sheet shows you when you hover your mouse over the max hit points. For example, this reference will not work: [*S:hp_max]. Instead, you need to use this reference: [*S:hp^].<br />
<br />
If your ID refers to a token, token attributes can be accessed by preceding the attribute name with "t-", for example [*S:t-aura1_radius]. Supported token attributes are:<br />
<br />
{|<br />
| t-name || t-id || t-statusmarkers || t-bar1_value<br />
|-<br />
| t-bar1_max || t-bar2_value || t-bar2_max || t-bar3_value<br />
|-<br />
| t-bar3_max || t-top || t-left || t-width<br />
|-<br />
| t-height || t-rotation || t-layer || t-aura1_radius<br />
|-<br />
| t-aura1_color || t-aura2_radius || t-aura2_color || t-aura1_square<br />
|-<br />
| t-aura2_square || t-tint_color || t-light_radius || t-light_dimradius<br />
|-<br />
| t-light_angle || t-light_losangle || t-light_multiplier || t-light_otherplayers<br />
|-<br />
| t-light_hassight || t-flipv || t-fliph || t-controlledby<br />
|-<br />
| t-_cardid || t-_pageid || t-imgsrc || t-bar1_link<br />
|-<br />
| t-bar2_link || t-bar3_link || t-represents || t-layer<br />
|-<br />
| t-isdrawing || t-name || t-gmnotes || t-showname<br />
|-<br />
| t-showplayers_name || t-showplayers_bar1 || t-showplayers_bar2 || t-showplayers_bar3<br />
|-<br />
| t-showplayers_aura1 || t-showplayers_aura2 || t-playersedit_name || t-playersedit_bar1<br />
|-<br />
| t-playersedit_bar2 || t-playersedit_bar3 || t-playersedit_aura1 || t-playersedit_aura2<br />
|-<br />
| t-lastmove || t-adv_fow_view_distance || t-has_bright_light_vision || t-has_night_vision<br />
|-<br />
| t-night_vision_distance || t-emits_bright_light || t-bright_light_distance || t-emits_low_light<br />
|-<br />
| t-low_light_distance || t-has_limit_field_of_vision || t-limit_field_of_vision_center || t-limit_field_of_vision_total<br />
|-<br />
| t-has_limit_field_of_night_vision || t-limit_field_of_night_vision_center || t-limit_field_of_night_vision_total || t-has_directional_bright_light<br />
|-<br />
| t-directional_bright_light_center || t-directional_bright_light_total || t-has_directional_dim_light || t-directional_dim_light_center<br />
|-<br />
| t-directional_dim_light_total || t-lightColor || || |<br />
|}<br />
<br />
'''''It is important to note that some attributes names on tokens have corresponding attribute names on characters, which represent different values. For example, [*T:id] returns the character ID, while [*T:t-id] returns the token ID.'''''<br />
<br />
=== Subroutine Parameters ===<br />
<br />
When using a gosub statement (-->) or a conditional marked as a gosub (prefixing the label with a > character), you can pass any number of parameters separated by semicolons (;) that the code in the subroutine can utilize.<br />
<br />
Subroutine parameters are numbered starting at 1, and are accessed by using the notation [%number%], so the first parameter is [%1%], the second is [%2%], etc.<br />
<br />
Parameter substitution happens on all line types, and happens prior to character attribute references or roll variable substitution.<br />
<br />
=== Campaign Attribute ===<br />
You can retrieve properties of the API's Campaign object with the [*C:attributename] syntax. For example, [*C:playerpageid] will retrieve the current player ribbon page from the Campaign object.<br />
<br />
=== Page Attributes ===<br />
If you have set the '''activepage''' parameter, you can retrieve page-related properties with the [*P:attributename] syntax, including the page's UDL parameters.<br />
<br />
=== Repeating Section Values ===<br />
<br />
You can reference repeating attribute data using the syntax [*R:attributename] syntax (similar to referencing standard character attributes). The currently active repeating row information will be used to retrieve attribute values. You can also retrieve the full attribute name for a repeating row attribute by using the [*R>attributename] notation. This is useful to pass to things like chatsetattr.<br />
<br />
See the section named [[#Repeating Section Access (--R)|Repeating Section Access]] for more information.<br />
<br />
=== Array Elements ===<br />
After an array has been declared, the elements can be referenced with [@arrayName(index)]. Array indices start at 0.<br />
<br />
== Deferred Resolution for Meta Scripts ==<br />
<br />
As of 1.2.9, ScriptCards supports a deferral character for use when calling another API script with via the <code>--@</code> statement, to defer processing of meta script references so they get processed prior to the sub-API call instead of prior to ScriptCards execution. To defer this processing for meta script ([[Tim#SelectManager|SelectManager]], [[Tim#Fetch|Fetch]]) by inserting a deferral character into the meta call. For example, if I want to have ScriptCards call [[TokenMod]] as if the token for "Quej Gr'stra" (yes, I let Roll20 name my test NPCs) I could use something like this:<br />
<br />
<pre> --@token-mod|{^& select Quej Gr'stra} _on showname</pre><br />
<br />
The <code>^</code> in between <code>{</code> and <code>&</code> will prevent SelectManager from seeing the call when the ScriptCard script is processed, but the <code>--@</code> statement will remove the deferral character so the command that will be sent by ScriptCards is:<br />
<br />
<pre>!token-mod {& select Quej Gr'stra} --on showname</pre><br />
<br />
With the deferral character removed, SelectManager will see the <code>{& select ...}</code> and do its magic.<br />
<br />
While the default deferral character is <code>^</code>, the deferral character is a setting that can be changed:<br />
<br />
<pre> --#deferralcharacter|%</pre><br />
<br />
Will make <code>%</code> the deferral character for future <code>--@</code> statements in the running script.<br />
<br />
Supported [[API:Meta_Scripts|Meta Script]] structures:<br />
* <code>{^&...}</code> - for [[Tim#SelectManager|SelectManager]]<br />
* <code>@^(...)</code> and <code>*^(...)</code> for [[Tim#Fetch|Fetch]]<br />
* <code>get^.</code> and <code>set^.</code> for [[Tim#Fetch|Muler]] (''''' v 1.4.5+ ''''')<br />
<br />
== Arrays ==<br />
<br />
Arrays are a new data type introduced in version 1.1.12 of ScriptCards, and are manipulated with associated function (--~) commands.<br />
<br />
* Arrays are a lists of strings. Items in an array cannot contain the semi-colon (;) character, as that is used to separate parameters in the function code that deals with arrays.<br />
* Arrays are accessed via the --~ script command. In some cases, the value of the tag (variable name) for array commands is not used, and can be a dummy value or simply omitted. I have omitted them in the statements below.<br />
* All commands that DO return a value return string values, even if the content is numeric.<br />
* If a command returns a value and there is some sort of reason that it isn't an array value, you will get "ArrayError" in the return value. This can happen if you reach the end of an array while stepping through it, for example, so checking for "ArrayError" can serve as the end condition for a loop.<br />
* Each array keeps track of its current index, allowing you to step forward and backwards through arrays.<br />
* Any number of arrays can be defined.<br />
* Unlike string variables and roll variables, array variables cannot (currently) be referenced directly. It is necessary to use the function (--~) syntax to manipulate arrays and get values from them as strings for use in other parts of your script.<br />
<br />
== Reentrant Scripts ==<br />
<br />
Reentrant scripts allow you to create buttons in your script code that will re-execute the script at a given label within the code. If you set the reentrant setting (<code>--#reentrant|somevalue</code>) to a non-zero value, your setting and variable information will be preserved between executions. Reentrant script can be used to present menus or choices and then continue acting.<br />
<br />
'''''Important''''': The value of the reentrant setting will be used to identify the appropriate script to resume when reentrancy is used. If more than one character can potentially run the same script at the same time, it is a good practice to include the character ID in the reentrant setting in order to maintain a separate list of variables. Something like:<br />
<br />
<pre><br />
--#reentrant|My Cool Script @{selected|character_id}<br />
</pre><br />
<br />
Reentrant buttons are created with the <code>[rbutton]Caption::ReentryLabel;Parameter[/rbutton]</code> construct. The caption will be displayed on the generated button. <code>ReentryLabel</code> is the name of a label in your script that the button will jump to when clicked, and Parameter will be passed in as a string value called <code>reentryval</code>.<br />
<br />
Example:<br />
<pre><br />
!script {{<br />
--#reentrant|testing<br />
--=Roll|1d20<br />
--+Roll|[$Roll]<br />
--&String|That was a [$Roll.Raw]!<br />
--~x|array;define;MyArray;Apple;Banana;Orange<br />
--+Try it|[rbutton]Hello!::EXEC_PC_SPELL;9[/rbutton]<br />
--X|<br />
<br />
--:EXEC_PC_SPELL|<br />
--+ReentryVal|[&reentryval]<br />
--+The value of Roll is|[$Roll]<br />
--+Value of String|[&String]<br />
--+Array|[@MyArray(0)]<br />
--X|<br />
}}<br />
</pre><br />
<br />
This script sets up some variables and then displays a button labeled "Hello!". If the user clicks the button, the script will be re-entered starting at <code>EXEC_PC_SPELL</code>, which will display the content of the variables from the original execution.<br />
<br />
'''''Note: This section needs to be expanded upon'''''<br />
<br />
==Libraries ==<br />
=== Procedure Libraries ===<br />
<br />
You can now create [[handouts]] in your game in Roll 20 with the name format "ScriptCards Library NAME", where name is a name you assign to the library. Library names are case sensitive. It is my hope that the more proficient ScriptCards scripters out there will provide procedure libraries (or procedures that can be included in libraries) for others to use to make their scripting life easier. Be they specific to a game system, or to a type of activity, I think a robust set of libraries that GMs could use to enhance their scripting capabilities would be very valuable to the community. Should such things begin to emerge, I’ll create a portion of the ScriptCards Wiki page to house them.<br />
<br />
To include one or more libraries in a script, use the +++libname+++ directive (does not need a -- line associated with it). Multiple library names can be specified by separating them with semicolons (i.e., +++General;dnd5elib;Colorize+++ would include three libraries (General, dnd5elib, and Colorize).<br />
<br />
Included libraries are separated from the main script code by the automatic inclusion of "--X|" before the first library is appended to the script, and all libraries are loaded at the end of the script before script processing takes place.<br />
<br />
Procedures and labels in libraries can be used just as if they were included in the body of your script. Note that this DOES mean that you could, technically, jump into a library with a direct branch (--^) or direct branch conditional, but I recommend using libraries to store reusable procedures.<br />
The Notes section of the library handout stores the library code, and is written just like any other ScriptCards code except:<br />
<br />
* They cannot use roll queries (?{Some Prompt:}) to get information from the user at execution time.<br />
* They cannot use @{} notation to access character and token information.<br />
<br />
Both of these limitation stem from the fact that Procedure Libraries are not processed by the chat server, which is what handles these items.<br />
<br />
Here is an example of handling damage modifications (resistance, vulnerability, and immunity) in D&D 5E with a library:<br />
<br />
<pre><br />
!script {{<br />
+++dnd5elib+++<br />
--#|Damage Modifiers Test<br />
--#targettoken|@{target|token_id}<br />
-->Lib5E_CheckDamageModifiers|ResistType;fire<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] fire damage<br />
<br />
-->Lib5E_CheckDamageModifiers|ResistType;cold<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] cold damage<br />
<br />
-->Lib5E_CheckDamageModifiers|ResistType;poison<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] poison damage<br />
<br />
-->Lib5E_CheckDamageModifiers|ResistType;acid<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] acid damage<br />
<br />
--X|<br />
}}<br />
</pre><br />
<br />
Library content (In a handout called “ScriptCards Library dnd5elib” NOTE: Paste into Notepad first and then paste into the handout in Roll20 to avoid bringing over HTML formatting from the web site):<br />
<br />
<pre><br />
--/|ScriptCards Library: dnd5elib version 0.0.1<br />
--/|Provides various utility procedures for D&D 5E games<br />
<br />
--/|Lib5E_CheckDamageModifiers handle damage resistance, vulnerability, and immunity. <br />
--/|Pass a string variable to be filled with a string to be appended to a dice roll and the damage type <br />
<br />
--:Lib5E_CheckDamageModifiers|damageVariableName;damageType<br />
--&[%1%]|<br />
--?"[*T:npc_vulnerabilities]" -inc "[%2%]"|>_Lib5E_IsVulnerable;[%1%]<br />
--?"[*T:npc_resistances]" -inc "[%2%]"|>_Lib5E_IsResistant;[%1%]<br />
--?"[*T:npc_immunities]" -inc "[%2%]"|>_Lib5E_IsImmune;[%1%]<br />
--<|<br />
<br />
--:_Lib5E_IsVulnerable| --&[%1%]| * 2 [Vulnerable] --<|<br />
--:_Lib5E_IsResistant| --&[%1%]| \ 2 [Resistant] --<|<br />
--:_Lib5E_IsImmune| --&[%1%]| * 0 [Immune] --<|<br />
</pre><br />
<br />
The idea is that the functions in the library create a string that can be appended to a roll to modify the output based on resistances, so you pass Lib5E_CheckDamageModifiers the name of the string variable you want to use and the damage type. The variable (ResistType in this case) will include either nothing, “* 2 [Vulnerable]”, “\ 2 [Resistant]”, or “* 0 [Immune]” which can be included in a roll assignment (--=) to modify the damage as appropriate. The order here might be important if an NPC is misconfigured to be both resistant and immune to the same damage type. Since immune is an absolute, having it last ensures that it will override resistant or vulnerable. A creature that is both vulnerable and resistant (again, misconfigured) will come back as resistant since that condition is checked after vulnerable.<br />
Some notes: I prefix my library labels with either “Lib5E_” or “_Lib5E_” as a clarity convention. This isn’t strictly necessary but you should be aware that if two libraries (or if your script and a library) define the same label, the last label defined will win. Since libraries are appended to the end of the script in the order you include them in the +++libname+++ directive, you can somewhat control this, but it is probably best to avoid re-declaring labels. <br />
<br />
In my case, items beginning with “Lib5E_” are intended to be called by scripts, while items beginning with “_Lib5E_” are intended to be used as subroutines by the “public” procedures. Of course, there is no reason you couldn’t call them directly.<br />
<br />
You might also note that I’ve included some library information in comment lines (--/|) at the top of the library. These are ignored by ScriptCards, and are a good way to convey requirements, parameters, usage information, etc.<br />
<br />
=== Example Libraries ===<br />
<br />
==== dnd5elib ====<br />
<br />
[https://github.com/kjaegers/ScriptCards Download the dnd5elib Library from the ScriptCards GitHub]<br />
<br />
The '''dnd5elib''' library provides a collection of utility procedures that help simplify dealing with the D&D 5E Official Sheet. Some of the procedures in this library require '''chatsetattr''' to be installed in your game. This is a growing library, and currently only has a handful of routines. They are:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Procedure Name !! Notes<br />
|-<br />
| style="white-space:nowrap" | Lib5E_CheckDamageModifiers || This procedure can be used to evaluate vulnerabilities, resistances, and invulnerabilities on an NPC. After setting the --#target| parameters, pass the Lib5E_CheckDamageModifiers procedure a variable name (no reference information) and a damage type (i.e., fire, cold, bludgeoning, etc.), and the procedure will then create a string variable with with a name equal to the first parameter that you passed into the procedure. This variable will contain a string that can be included in a roll line (--=), in order to modify the roll as appropriate. For example, '''-->Lib5E_CheckDamageModifiers|ResistType;fire''' will check the current target character's attributes for "fire" and will either return an empty string (no references), "* 0 [Immune]" if the creature is immune, "\ 2 [Resistant]" if the creature is resistant, or "* 2 [Vulnerable]" if the creature is vulnerable to fire damage.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_DeductSpellSlot || Pass in a character_id and a slot level, and the script will expend one spell slot of that level, capping the value at 0 slots remaining. For Example '''<nowiki>-->Lib5E_DeductSpellSlot|@{selected|character_id};1</nowiki>''' to deduct a first level spell slot from the selected character.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_FindResource || Used to locate a resource value on a character. Pass in a character_id, a resource name, and two variable names. The procedure will check both repeating and non-repeating resources looking for a resource whose name matches what was passed in and return three variables. The first will be a string variable named for the 3rd parameter and contains the attribute name of the resource's "name" field. The second will be a string variable named after parameter 4 and contains the resource's value field attribute name, and the third variable is a Roll Variable, also named after the 4th parameter that contains the current resource value. Example: '''<nowiki>-->Lib5E_FindResource|@{selected|character_id};Crossbow bolts;ResName;ResValue</nowiki>''' will find "Crossbow bolts" as a resource on the character and return [&ResName] which is the name of the resource attribute, [&ResValue] which is the '''name of the attribute that stores the value''' and [$ResValue] which is the current numeric value of the resource.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Global_Attack_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Attack Modifiers (repeating_tohitmod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Bless" for 1d4 active and "Being Cool" for +2 active, I will get a return string " + 1d4 [Bless] + 2 [Being Cool]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Save_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Save Modifiers (repeating_savemod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Bless" for 1d4 active and "Being Cool" for +2 active, I will get a return string " + 1d4 [Bless] + 2 [Being Cool]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Skill_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Skill Modifiers (repeating_skillmod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Guidance" for 1d4 active and "Being Cool" for +2 active, I will get a return string " + 1d4 [Guidance] + 2 [Being Cool]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_AC_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Save Modifiers (repeating_savemod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Shield of Faith" with a value of 2 active, I will get a return string " + 2 [Shield of Faith]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Damage_Modifiers || Pass a character ID and TWO string variable to set the return value. The first string will be for normal damage, and the second will be the additional damage on a crit. This procedure will look through the Global Damage Modifiers (repeating_damagemod_*) for rows that are active (checked on the character sheet) and return two strings with the dice rolls and descriptions for them (for example, if I have "Sneak Attack" with a value of 1d6 normal and 1d6 critical damage active, I will get a return string " + 1d6 [Sneak Attack]" and another string of " + 1d6 [Sneak Attack CRIT]" that can be used in a dice rolls.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_DivineSmiteDice || Used to calculate the number of dice to be rolled for a paladin's Divine Smite. Pass a target token id, a spell slot level, and a string variable to be set to the dice roll amount based on the NPC_TYPE attribute of the target token. The returned variable will contain a dice roll (like "3d8" that can be used in a --= line)<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Character_Summary || Pass a character ID to outputs a mini character sheet, including clickable buttons for attacks, actions, legendary actions, etc. Will automatically detect a PC vs NPC and output the appropriate sections.<br />
|}<br />
<br />
Due to formatting issues with the Wiki, the library code has been moved to a [https://gist.github.com/kjaegers/52f6049ddd257f0a1288aca4bbde13c5 GITHUB GIT]. Please view the GIST in raw mode and copy the text and paste it into a handout called "ScriptCards Library dnd5elib" in your Roll20 Game.<br />
<br />
== What to Know if you are Coming from PowerCards ==<br />
<br />
''Note: This section is a work in progress.''<br />
<br />
While ScriptCards and PowerCard have very similar output goals, their internals and use are quite different. The table below summarizes some of the major differences between the scripts.<br />
<br />
::{| class="wikitable"<br />
|-<br />
! PowerCards !! ScriptCards <br />
|-<br />
| With a handful of exceptions, all lines in a PowerCard macro are intended to produce a line of output on the final card. || With ScriptCards, ONLY the <code>--+</code> and <code>--*</code> statement types produces output <br />
|-<br />
| PowerCards lines begin with two dashes (<code>--</code>) followed by a unique tag name for the line, followed by a vertical bar and the content for the line. || ScriptCards lines begin with two dashes (<code>--</code>) followed by a '''statement type identifier''', which is a single character that identifies the type of line to the interpreter. This is followed by a tag (frequently optional), a vertical bar, and the parameters for the statement being executed.<br />
|-<br />
| PowerCard macros are always processed top to bottom. Lines can be hidden so they don't output anything, but there is no looping or branching (<code>--SkipTo</code> looks like a branch, but it just hides all of the lines until the referenced label. || ScriptCards scripts support true branching, including direct branching (<code>--^</code>) and procedure branching (<code>--></code>) and (<code>--<</code>). Procedures support parameters and a call stack so procedures can be nested to call other procedures.<br />
|-<br />
| All lines in a PowerCards macro need to have unique tags because PowerCards builds the card as a single JavaScript object using the tag names to store what will be displayed. This is why repeated tag names always result in the last one being shown. || ScriptCards tags do not need to be unique, and in the case of many line types are optional.<br />
|-<br />
| PowerCards conditionals result in either showing or hiding the line they are on. || ScriptCards conditionals '''''only''''' support branching as the result of the comparison. This branching can be direct (a GOTO) or procedural (a GOSUB) '''''NOTE: As of version 1.2.0, ScriptCards also supports roll/string variable assignment as a result of conditional evaluation, and later versions introduced code blocks that can be implemented as a result of a conditional'''''<br />
|-<br />
| PowerCards relies on the Roll20 [[Quantum Roll]] server and [[Inline|inline rolls]] for all dice functions || ScriptCards includes its own dice roll parser, and '''''does not support''''' [[Inline|inline rolls]]. '''''Note: As of version 1.2.3, ScriptCards will parse [[Inline|inline rolls]], inserting their final value in the place of the roll in the macro, but they are not part of or parsed by the built-in roll parser'''''<br />
|-<br />
| PowerCards RollIDs (often mistaken for variables) are assigned by analyzing the results of an inline roll, and cannot be referenced in other rolls, so you can't roll a <code>1d4</code> and then roll a <code>1d20</code> and add the <code>1d4</code> result because all of the rolls happen on the chat server before PowerCards gets the macro text. || ScriptCards supports two types of variables: <code>Roll Variables</code> and <code>String Variables</code>. Because ScriptCards uses its own roll parser and is not dependent upon the chat server, rolls and their results can be used in other rolls, math functions, output, etc.<br />
|}<br />
<br />
== Example Scripts ==<br />
<br />
'''''Note: The features available in ScriptCards have changed drastically since these examples were written. While these should still work, there are in many cases better ways to do things using language features introduces after these were constructed. Please see the [https://github.com/kjaegers/ScriptCards/tree/main/ScriptExamples Script Examples] section of the official ScriptCards GitHub repository for more updated script examples.<br />
<br />
Below are some sample scripts that utilize the various statement types in ScriptCards:<br />
<br />
=== Divine Smite ===<br />
<br />
This script will prompt the user for a spell slot level to expend on a divine smite. It will check the target's npc_type to see if it is an Undead or Fiend, which adds an additional d8 to the smite roll.<br />
<br />
[[File:ScriptCards Divine Smite.png|Divine Smite Script Output]]<br />
<br />
<pre><br />
!scriptcard {{<br />
--#title|Divine Smite<br />
--=DiceCount|?{Spell Slot Level?|1|2|3|4|5|6|7|8|9} + 1<br />
--=IsFiendOrUndead|0<br />
--?"@{target|npc_type}" -inc fiend|>IsBoosted<br />
--?"@{target|npc_type}" -inc undead|>IsBoosted<br />
--=TotalDice|[$DiceCount] + [$IsFiendOrUndead]<br />
--=SmiteRoll|[$TotalDice]d8<br />
--#emoteText|@{selected|token_name} smites @{target|token_name}<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
--+Smite|deals [$SmiteRoll] radiant damage.<br />
--X|<br />
<br />
--:IsBoosted|<br />
--=IsFiendOrUndead|1<br />
--<|<br />
}}<br />
</pre><br />
<br />
==== How It Works ====<br />
<br />
The first line sets the "title" card parameter to "Divine Smite".<br />
<br />
Line 2 Shows a query to the user asking for the spell slot level, adds one and stores the value in the "DiceCount" Roll Variable. The query/dropdown is generated by the chat server prior to the script being executed.<br />
<br />
Line 3 defaults the "IsFiendOrUndead" Roll Variable to 0.<br />
<br />
Lines 4 and 5 compare the target's "npc_type" attribute (passed by the chat server as text) to see if they include either "undead" or "fiend". If true, the IsBoosted subroutine will be called. No parameters are passed to this subroutine.<br />
<br />
Line 6 sets the "TotalDice" variable to the base (DiceCount) number plus the IsFiendOrUndead number, which will be a 0 or a 1.<br />
<br />
Line 7 calculates "SmiteRoll" by rolling a number of d8 equal to the "TotalDice" value.<br />
<br />
Lines 8-10 set the parameters for the emote, which appears above the card content. By setting the sourceToken and the targetToken, their icons will appear in the emote surrounding the text describing the action.<br />
<br />
Line 11 is the only line that actually produces output on the card. It results in "Smite deals # radiant damage".<br />
<br />
Line 12 ends the script execution, preventing the script from continuing and running the subroutines out of context.<br />
<br />
Lines 14-16 are the IsBoosted subroutine, starting with the :IsBoosted label. The IsFiendOrUndead variable is set to 1, and a return from subroutine is executed.<br />
<br />
=== Magic Missile ===<br />
<br />
This script demonstrates using a loop and calling a subroutine to fire a number of missiles determine by the spell slot level used to cast the spell.<br />
<br />
[[File:ScriptCards_MagicMissile_Fixed.png|Magic Missile Script Output]]<br />
<br />
<pre><br />
!scriptcard {{ <br />
--#title|Magic Missile<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
--=MissileCount|?{Spell Slot Level?|1|2|3|4|5|6|7|8|9} + 2<br />
--=DisplayCount|1<br />
--=MissileDamage|0<br />
--#leftsub|Slot level ?{Spell Slot Level?}<br />
--#rightsub|Ranged Attack<br />
--#emoteText|Fred uses a level ?{Spell Slot Level?} spell slot to fire [$MissileCount.Total] missiles of magical force!<br />
--:MissileLoop|<br />
-->FireMissile|<br />
--=DisplayCount|[$DisplayCount] + 1<br />
--?[$DisplayCount] -le [$MissileCount]|MissileLoop<br />
--+Total|Total damage is [$MissileDamage]<br />
--X|<br />
<br />
--:FireMissile|<br />
--=ThisMissile|1d4 + 1<br />
--=MissileDamage|[$MissileDamage] + [$ThisMissile]<br />
--+Missile|[$DisplayCount.Total] Hits for [$ThisMissile] [b]force[/b] damage<br />
--<|<br />
}}<br />
</pre><br />
<br />
==== How It Works ====<br />
<br />
Lines 1-3 set the card title, the source token and the target token. Setting these tokens causes their icons/avatars to appear in the Emote section of the card.<br />
<br />
Line 4 asks the user what spell slot level they wish to use to cast magic missile. The number of missiles fired is equal to 2 plus the spell level, and this is stored in the MissileCount variable.<br />
<br />
Line 5 stores a 1 in the DisplayCount variable. This will be used to control the loop to determine the number of missiles fired and the missile number when displaying damage rolls.<br />
<br />
Line 6 initializes MissileDamage to 0<br />
<br />
Line 7 sets the left subtitle to the text "Slot Level #", where # is the spell slot level being used.<br />
<br />
Line 8 sets the right subtitle to the text "Ranged Attack".<br />
<br />
Line 9 sets the emoteText parameter with a description of the action, including the slot level and number of missiles fired.<br />
<br />
Line 10 is a label for the missile firing loop<br />
<br />
Line 11 Calls the "FireMissile" subroutine<br />
<br />
Line 12 increases the DisplayCount variable by 1<br />
<br />
Line 13 Checks to see if there are still missles to fire (DisplayCount <= MissileCount) and if so branches to MissileLoop<br />
<br />
Line 14 Displays the total damage dealt by the spell.<br />
<br />
Line 15 stops execution of the script to prevent out of context execution of the subroutine.<br />
<br />
Lines 76-21 are the FireMissile subroutine, beginning with the FireMissile label. The 1d4+1 is rolled and assigned to "ThisMissile". The result is added to the existing MissileDamage total, and a line for the current missile is displayed with the missile number and the damage for the missile.<br />
<br />
=== Longsword Attack ===<br />
<br />
This script demonstrates a standard 5E D&D melee weapon attack, including detection of misses, fumbles, hits, and critical hits. If installed, alterbars is used to decrement the target's BAR3 value by the damage dealt.<br />
<br />
[[File:ScriptCards Longsword.png|Longsword Script Output]]<br />
<br />
<pre><br />
!scriptcard {{<br />
--#title|Longsword<br />
--#leftsub|Melee Attack<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
--#emoteText|@{selected|token_name} attacks @{target|token_name}<br />
--=TargetAC|@{target|npc_ac}<br />
--?[$TargetAC.Total] -gt 0|DoneWithAC<br />
--=TargetAC|@{target|ac}<br />
--:DoneWithAC|<br />
--=AttackRoll|1d20 + @{selected|strength_mod} [STR] + @{selected|pb} [PROF]<br />
--+Attack|@{selected|token_name} rolls [$AttackRoll] vs AC [$TargetAC].<br />
--?[$AttackRoll.Base] -eq 20|Crit<br />
--?[$AttackRoll.Base] -eq 1|Fumble<br />
--?[$AttackRoll.Total] -ge [$TargetAC.Total]|Hit<br />
--+Miss|The attack missed.<br />
--^Final|<br />
<br />
--:Fumble|<br />
--+Fumble!|The attack went horribly wrong.<br />
--^Final|<br />
<br />
--:Hit|<br />
--=Damage|1d8 + @{selected|strength_mod} [STR]<br />
--+Hit!|The attack hit @{target|token_name} for [$Damage] slashing damage.<br />
--@alter|_target|@{target|token_id} _bar|3 _amount|-[$Damage]<br />
--^Final|<br />
<br />
--:Crit|<br />
--=Damage|1d8 + @{selected|strength_mod} [STR] + 1d8 [CRIT]<br />
--+Critical Hit!|The attack hit @{target|token_name} for [$Damage] slashing damage.<br />
--@alter|_target|@{target|token_id} _bar|3 _amount|-[$Damage]<br />
<br />
--:Final|<br />
}}<br />
</pre><br />
<br />
==== How it Works ====<br />
<br />
In lines 1-5, we set the title, subtitle, and emote text along with the tokens for the emote area.<br />
<br />
Lines 6-9 allow us to determine the AC of the target. On the 5E Roll20 sheet, NPCs armor class is stored in "npc_ac", while PCs armor class is in "ac". First we grab npc_ac and if it is zero, we check AC.<br />
<br />
Line 10 rolls the attack roll, rolling 1d20 and adding the attacker's strength modifier and proficiency bonus<br />
<br />
Line 11 displays the result of the attack roll on the card<br />
<br />
Lines 12-14 determine what kind of result the attack had. If the .Base value of the roll was 20, we branch to "Crit". If it was 1, we branch to "Fumble". If the .Total value of the roll was greater than or equal to the AC that was determined in Lines 6-9, we branch to Hit.<br />
<br />
Assuming we didn't branc anywhere, the result of the attack was a miss, so we display that on line 15 and then branch to "Final"<br />
<br />
This is followed by three branch segments, :Fumble, :Hit, and :Crit. A fumble displays a text message and branches to :Final.<br />
<br />
On a hit or a crit, we roll Damage (adding additional damage dice on a crit). We display a "Hit!" or "Critical Hit!" message and then make an API call to AlterBars, passing it the token id, bar we want to modify (3 in this case), and the amount we want to modify by the Damage value.<br />
<br />
=== Party Health Status ===<br />
<br />
This example calculates the current Hit Points remaining and HP percentage for each character and creates a color-coded display with the current party status.<br />
<br />
[[File:ScriptCards Party Health.png]]<br />
<br />
<pre><br />
!scriptcard {{<br />
--#title|Party Status<br />
--#titleCardBackground|#33CC33<br />
--#oddrowbackground|#bfee90<br />
--#evenrowbackground|#90eebf<br />
-->HealthCheck|@{Quej Grastra|character_id}<br />
-->HealthCheck|@{Brim Cheuto|character_id}<br />
-->HealthCheck|@{Odug Ututees|character_id}<br />
--X|End of card Execution<br />
<br />
--:HealthCheck|<br />
--=HealthPerc|[*[%1%]:hp] / [*[%1%]:hp^] * 100 \ 1<br />
--=HealthColor|000000<br />
--?[$HealthPerc.Total] -gt 50|HealthSkip<br />
--=HealthColor|FF0000<br />
--:HealthSkip|<br />
--+[*[%1%]:character_name]|has [#[$HealthColor.RollText]][*[%1%]:hp] of [*[%1%]:hp^][/#] HP [R]([$HealthPerc.Total]%)[/R]<br />
--<|End of HealthCheck<br />
}}<br />
</pre><br />
<br />
==== How it Works ====<br />
<br />
Lines 1-4, we set the card title, and set the title background and row background colors to shades of green.<br />
<br />
Lines 5-7 make gosub calls the the "HealthCheck" subroutine, passing in the character ID of each of the named characters (these are the names of the characters in my test game)<br />
<br />
Line 8 terminates the script execution.<br />
<br />
The remaining lines of the script are the HealthCheck subroutine, which works like this:<br />
<br />
Line 10 is the subroutine label (:HealthCheck)<br />
<br />
Line 11 uses the character id passed as a parameter and combines it with character attribute lookup *(...) to retrieve the value of "hp" and "hp<nowiki>^</nowiki>" for the character. The <nowiki>^</nowiki> character is used to specify that we want the MAX value for this attribute for the second call. We divide these two numbers and multiple by 100 to get a percentage. Finally, we use integer division by 1 to round the percentage and drop the decimals. The end result gets stored in the HealthPerc roll variable.<br />
<br />
Line 12 defaults to color of the health text to black<br />
<br />
Line 13 check to see if the health percentage is greater than 50. If so, it branches to HealthSkip, preventing the script from executing line 13.<br />
<br />
Line 14 sets the color of the health text to red<br />
<br />
Line 15 is the label that will be branched to from Line 13 to skip the red coloring<br />
<br />
Line 16 again uses character attribute substitution and the passed parameter value to output a display line containing the character name, the colorized health total, and the percentage value. The percentage is right-justified.<br />
<br />
Line 17 returns from the HealthCheck subroutine.<br />
<br />
=== Expanded Magic Missile Script ===<br />
<br />
This is the expanded and enhanced version of the Magic Missile script covered in {{yt|watch?v=u50xvNzS9Zk | this video}}. It includes visual and audio effects, checking and deducting spell slots, and applying damage using either Token-Mod or Alterbars.<br />
<br />
<pre><br />
!scriptcard {{ <br />
--#title|Magic Missile<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
<br />
-->GetAndCheckSlotInformation|<br />
<br />
--=MissileCount|[$SlotLevel] + 2<br />
--=DisplayCount|1<br />
--=MissileDamage|0<br />
--#leftsub|Slot level [$SlotLevel]<br />
--#rightsub|Ranged Attack<br />
--#emoteText|@{selected|character_name} uses a level [$SlotLevel.Total] spell slot to fire [$MissileCount.Total] missiles of magical force!<br />
<br />
--:MissileLoop|<br />
-->FireMissile|<br />
--=DisplayCount|[$DisplayCount] + 1<br />
--?[$DisplayCount] -le [$MissileCount]|MissileLoop<br />
--+Total|Total damage is [$MissileDamage]<br />
-->DeductSpellSlot|<br />
--#rightsub|Level [$SlotLevel] Left: [$SlotsRemaining] <br />
-->PlayEffects|none;burst-smoke;beam-magic;spell_01<br />
-->ApplyDamageTokenmod|@{target|token_id};3;-[$MissileDamage]<br />
-->ApplyDamageAlterbars|@{target|token_id};3;-[$MissileDamage]<br />
--X|<br />
<br />
--:FireMissile|<br />
--=ThisMissile|1d4 + 1<br />
--=MissileDamage|[$MissileDamage] + [$ThisMissile]<br />
--+Missile|[$DisplayCount.Total] Hits for [$ThisMissile] [b]force[/b] damage<br />
--<|<br />
<br />
--:GetAndCheckSlotInformation|<br />
--=SlotLevel|?{Spell Slot Level?|1|2|3|4|5|6|7|8|9}<br />
--=SlotsTotal|[*S:lvl[$SlotLevel]_slots_total]<br />
--=SlotsExpended|[*S:lvl[$SlotLevel]_slots_expended]<br />
--?[$SlotsExpended.Total] -ge [$SlotsTotal.Total]|NoSlotsLeft<br />
--<|<br />
<br />
--:NoSlotsLeft|<br />
--+|[*S:character_name] has no level [$SlotLevel.Total] spell slots available.<br />
--X|<br />
<br />
--:DeductSpellSlot|<br />
--=SlotsExpended|[$SlotsExpended] + 1<br />
--@setattr|_charid [*S:character_id] _lvl[$SlotLevel]_slots_expended|[$SlotsExpended] _silent<br />
--=SlotsRemaining|[$SlotsTotal] - [$SlotsExpended]<br />
--<|<br />
<br />
--:PlayEffects|Parameters are : source effect; target effect; line effect; sound effect<br />
--vtoken|@{selected|token_id} [%1%]<br />
--vtoken|@{target|token_id} [%2%]<br />
--vbetweentokens|@{selected|token_id} @{target|token_id} [%3%]<br />
--@roll20AM|_audio,play,nomenu|[%4%]<br />
--<|<br />
<br />
--:ApplyDamageTokenmod|Parameters are tokenid;bar#;amount<br />
--@token-mod|_ignore-selected _ids [%1%] _set bar[%2%]_value|[%3%]<br />
--<|<br />
<br />
--:ApplyDamageAlterbars|<br />
--@alter|_target|[%1%] _bar|[%2%] _amount|[%3%]<br />
--<|<br />
}}<br />
</pre><br />
<br />
===Hidden Roll===<br />
<br />
A roll where only the GM sees the result of the roll.<br />
[[File:Scriptcards-hiddenroll.png|right]]<br />
<pre><br />
!script {{<br />
--#title|Stealth Check<br />
--=Roll|1d20 + @{selected|stealth}<br />
--+|@{selected|token_name} attempts to move undetected...<br />
--*GMLine|@{selected|token_name} rolled a [$Roll]<br />
}}<br />
</pre><br />
<br />
===Elsewhere===<br />
* {{fpl|10000297/ Scritpcard API Working and Sharing}}<br />
* [https://gist.github.com/dubzilla1/cba439bd1f47ecdd81d0c79a482c4a91 Pathfinder 2E heal macros]<br />
<br />
[[Category:Featured articles]]</div>5004103https://wiki.roll20.net/Script:ScriptCardsScript:ScriptCards2022-02-10T10:08:00Z<p>5004103: /* Object Modification (--!) */</p>
<hr />
<div>{{revdate}}<br />
== Introduction ==<br />
'''ScriptCards''' provides a script interpreter that can be used to create powerful macros that display the results of player/NPC actions, or display other information in a pleasing visual format in your game's {{Text Chat}}. The scripting language contains variables (both dice-roll (enhanced numerics) and strings) as well, conditionals, branching, subroutines with parameters, and a set of built-in functions to simplify working with Roll20 information.<br />
{{script overview<br />
|name=ScriptCards<br />
|author=[[Kurt J.]]<br />
|code=ScriptCards<br />
|version=1.4.10<br />
|lastmodified=2021-12-04}}<br />
ScriptCards is not game-system specific, and can be used with any system/sheet. Near the end of this Wiki there is a section set aside for libraries that can implement system-specific tasks, with the hope that enthusiasts playing particular systems will create and share utility functions that can be utilized by the wider community.<br />
<br />
The default display style for ScriptCards output is similar to the format used to document player and NPC abilities in Dungeons and Dragons 4th Edition, but does not have any system ties to D&D4E.<br />
<br />
Current OneClick Version : 1.4.10<br />
'''''Note:''''' '''As of 2021-12-04, ScriptCards 1.4.10 has been submitted for OneClick update. The documentation below is in the process of being updated for 1.4.10.<br />
<br />
Current Development Version : 1.5.2<br />
<br />
'''''<big>Critically Important: ScriptCards does not use/parse [[Inline|inline rolls]]. ScriptCards includes its own built-in dice roll parser to allow for the use of variables inside dice rolls. As of version 1.2.3, ScriptCards will now take inline rolls and substitute the total result value in statement strings, meaning that you can utilize inline rolls but ScriptCards will only see the result of the roll, and not parse the roll components itself.</big>'''''<br />
{{#evp:youtube|hyR7Jnq4mQM|[[Script:ScriptCards|ScriptCards]] Introduction|right|650}}<br />
* {{fpl|9752053/ ScriptCards thread}}<br />
** {{fpl|10000297/ Scritpcard API Working and Sharing}}<br />
* {{repo|kjaegers/ScriptCards/tree/main/ScriptCards_API ScriptCards_API}} - GitHub repository for source before the one-click version is updated.<br />
* {{repo|kjaegers/ScriptCards/tree/main/ScriptExamples ScriptCards Samples}} - Branch of the GitHub repo that contains sample scripts.<br />
* {{yt.be|hyR7Jnq4mQM ScriptCards Intro}} 45min, Jan 2021<br />
* {{yt.be|u50xvNzS9Zk ScriptCards Magic Missile Deep Dive}} 39min, Feb 2021<br />
__TOC__<br />
=== Is ScriptCards Related to [[PowerCards]]? ===<br />
<br />
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.<br />
<br />
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 ({{code|name}}, {{code|leftsub}}, {{code|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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
Check the '''[[#What to Know if you are Coming from PowerCards|What to Know if you are Coming from PowerCards]]'''-section for a comparison table between the two scripts.<br />
<br />
=== What is a ScriptCard Script ===<br />
<br />
A ScriptCard Script is text written into the {{Text Chat}} (either typed directly, pasted, or run via a macro) that will produce a card of information in the [[Text Chat|chat window]]. A ScriptCard Script is composed of an [[API]] command: <code><nowiki>!scriptcard {{ }}</nowiki></code> enclosing any number of lines that determine the output that will be added to the card. At it simplest, the following macro:<br />
<br />
<pre>!scriptcard {{ }}</pre><br />
<br />
Will produce just a title card that displays “ScriptCards” as the name:<br />
<br />
[[File:Scriptcard blank.png]]<br />
<br />
Of course, this is just the simplest type of macro and isn’t very useful. In order to produce useful output, we need to include lines between the <code><nowiki>{{</nowiki></code> and <code><nowiki>}}</nowiki></code> that direct the API script as to what it should do.<br />
<br />
== Structure of a ScriptCard Line ==<br />
<br />
All ScriptCard lines begin with two dashes, followed by an ''statement identifier character'' that lets ScriptCards what type of line it is. There are several of these, and they are detailed in the next section. After the line type identifier, a Tag name 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.<br />
<br />
Following the Tag is a vertical bar, and then the content of the line itself. Again, each type of line might interpret this content differently.<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Identifier !! Statement Type !! Tag !! Content !! Notes<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--/</nowiki> || Comment || unused || unused || The <code>--/</code> 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--#</nowiki> || 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").<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--+</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--=</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--&</nowiki> || Assign String 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. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--@</nowiki> || 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 (i.e., [[TokenMod|!token-mod]], or [[ChatSetAttr|!setattr]], etc.)<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--:</nowiki> || 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<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--^</nowiki> || Branch To || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--></nowiki> || Call Procedure || 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<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--<</nowiki> || 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.<br />
|- <br />
| style="white-space:nowrap" | <nowiki>--?</nowiki> || Conditional Branch || Condition to be evaluated || True Branch Label<nowiki>|</nowiki>False Branch Label || The condition will be evaluated and execution will jump to one of the two indicated branches (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 included a semicolon separated list of parameters. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--s</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--l</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--v</nowiki> || 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+'''''<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--a</nowiki> || Play Audio Track || Unused || Jukebox track name (case sensitive) || Plays an audio track by name from the Roll20 jukebox. '''''Requires v1.5.2+'''''<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--e</nowiki> || Echo to Chat || Name to send chat command as || Chat message to send || Variable substitution takes place on the tag and content.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--R</nowiki> || Retrieve Repeating Section Row information || "find", "first", or "next" || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--~</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--c</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--i</nowiki> || Information Request || User Prompt;Button Caption || InfoType;VariableName;ParameterText || See full documentation below.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--d</nowiki> || 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. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--%</nowiki> || 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. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--*</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--!</nowiki> || Object Modification || <objectType>:<objectId> || setting:value|setting:value|setting:value... || Set properties of tokens/characters or character attributes ('''''v1.5.0+ required''''')<br />
|}<br />
<br />
== ScriptCard Statement Type Details ==<br />
The sections below detail the individual statement types supported by ScriptCards<br />
<br />
=== Comment (--/) ===<br />
<br />
A --/ statement is ignored by the ScriptCards parser. You can use this type of statement to add comments and informational text to your script. <br />
<br />
Example:<br />
<pre><br />
!script {{<br />
--/|Script Name : Fireball<br />
--/|Purpose : Allow the player to cast a fireball and blow stuff up!<br />
.<br />
.<br />
.<br />
}}<br />
</pre><br />
<br />
=== Set Parameter (--#) ===<br />
<br />
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.<br />
<br />
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.<br />
<br />
'''''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.'''''<br />
<br />
Examples:<br />
<pre><br />
--#title|Magic Missile<br />
--#leftsub|Level 1 Spell<br />
--#rightsub|Force Damage<br />
</pre><br />
<br />
The three examples above set the “title”, “leftsub”, and “rightsub” values for the card to the content value for the line. <br />
<br />
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.<br />
Settings Lines do not produce output lines on the card.<br />
<br />
The following settings are available (note that parameter names are ''not'' case sensitive):<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Name !! Effect/Use !! Default Value !! Type<br />
|-<br />
| 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<br />
|-<br />
| allowplaintextinrolls || If set to a non-zero value, plain character text in rolls will be copied to the roll text || 0 || Per-Line<br />
|-<br />
| bodyFontFace || Name of the font used in the card rows || Helvetica || Global<br />
|-<br />
| bodyFontSize || Size of the text in the card rows || 14px || Global<br />
|-<br />
| bodybackgroundimage || Specify an image (content for a CSS background-image tag) for the body area || none || Global<br />
|-<br />
| buttonBackground || Background color for buttons created with [button][/button] || #1C6EA4 || Per-Line<br />
|-<br />
| buttonBackgroundImage || A CSS specifier for a background image to use for buttons (i.e. url(...);) || empty || Per-Line<br />
|-<br />
| buttonBorderColor || Border (outline) color for buttons created with [button][/button] || #999999 || Per-Line<br />
|-<br />
| buttonFontFace || Font Family specifier for captions on buttons created with [button][/button] || Tahoma || Per-Line<br />
|-<br />
| buttonFontSize|| Text size for captions on buttons created with [button][/button] || x-small || Per-Line<br />
|-<br />
| buttonTextColor|| Text color of labels on buttons created with [button][/button] || #FFFFFF || Per-Line<br />
|-<br />
| 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<br />
|-<br />
| deferralcharacter || Changes the meta script deferral sequence to the specified value || ^ || Per-Line<br />
|-<br />
| diceFontColor|| Color of the dice created with the [d4] [d6], etc. formatting markers || #1C6EA4 || Per-Line<br />
|-<br />
| dicefontsize || Size of the dice created with the [d4] [d6], etc. formatting markers || 3.0em || Per-Line<br />
|-<br />
| 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<br />
|-<br />
| disablerollprocessing || If set to a non-zero value, --= lines will not process dice rolls strings || 0 || Per-Line<br />
|-<br />
| emoteBackground || Background color of the emote area || #f5f5ba || Global<br />
|-<br />
| emoteFont || Name of the font used in emote area (above the title of the output card) || Georgia || Global<br />
|-<br />
| emoteFontColor || Color of the font in the emote area || None (Empty) || Global<br />
|-<br />
| emoteFontSize || Size of the font used in the emote area || 14px || Global<br />
|-<br />
| emoteFontWeight || Font weight for the font in the emote area || bold|| Global<br />
|-<br />
| emoteState || If set to anything other than "visible", the emote portion of the card will not be displayed || visible || Global<br />
|-<br />
| emoteText || Text to display in the emote portion of the card || None (Empty) || Global<br />
|-<br />
| emotefont || Name of the font used in the emote text area || font-family: Georgia, serif; font-weight: bold; || Global<br />
|-<br />
| evenRowBackground || Hex code for the background color for even rows || #eeeeee || Per-Line<br />
|-<br />
| evenRowFontColor || Hex code for the text color for even rows || #000000 || Per-Line<br />
|-<br />
| evenrowbackgroundimage || Specify an image (content for a CSS background-image tag) for the even card rows || none || Per-Line<br />
|-<br />
| executionlimit || Maximum number of script lines the interpreter will try to execute. This prevents "infinite loop" sandbox crashes || 40000 || Global<br />
|-<br />
| hideCard || If set to any non-default value, the entire card output will be suppressed || 0 || Global<br />
|-<br />
| 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<br />
|-<br />
| 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<br />
|-<br />
| lineheight || Vertical size of each line on the output card || normal || Per-Line<br />
|-<br />
| nominmaxhighlight || If set to anything other than "0", rolls will not display crit/fumble/mixed highlight colors. || 0 || Per-Line<br />
|-<br />
| norollhighlight || If set to anything other than "0", rolls will not be formatted (plain numbers) but will still get a tooltip with details ('''''v1.3.6b+''''') || 0 || Per-Line<br />
|-<br />
| oddRowBackground || Hex code for the background color for even rows || #d0e4f5 || Per-Line <br />
|-<br />
| oddRowFontColor || Hex code for the text color for odd rows || #000000 || Per-Line<br />
|-<br />
| oddrowbackgroundimage || Specify an image (content for a CSS background-image tag) for the odd crd rows || none || Per-Line<br />
|-<br />
| reentrant || Used to name a script for rentrant button use || 0 || Global<br />
|-<br />
| 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)0 || Global<br />
|-<br />
| rollhilightcolorboth || Background box hilight color if both a 1 and a max on the die are rolled ('''''1.4.4+''''') || #8FA4D4 || Per-Line<br />
|-<br />
| rollhilightcolorcrit || Background box hilight color if the maximum number on the die was rolled ('''''1.4.4+''''') || #88CC88 || Per-Line<br />
|-<br />
| rollhilightcolorfumble || Background box hilight color if a 1 was rolled ('''''1.4.4+''''') || #FFAAAA || Per-Line<br />
|-<br />
| rollhilightcolornormal || Background box hilight color if neither a 1 or a max on the die are rolled ('''''1.4.4+''''') || #FFFEA2 || Per-Line<br />
|- <br />
| rollhilightlineheight || Determines the height of the hilight box placed around roll results ('''''1.4.2+''''') || 1.0em || Per-Line<br />
|-<br />
| roundUp || If set to a non-default value, integer division will round up instead of down || 0 || Per-Line<br />
|-<br />
| showfromfornonwhispers || If set to a non-zero value, will include the sender on cards that aren't whispered || 0 || Global<br />
|-<br />
| 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<br />
|-<br />
| subtitleFontColor || Color of the text in the subtitle areas || #FFFFFF || Global<br />
|-<br />
| subtitleFontFace || Name of the font used on the subtitle sections || Tahoma || Global<br />
|-<br />
| subtitleFontSize || Size of the subtitle font || 13px || Global<br />
|-<br />
| subtitleSeperator || The character(s) that will be placed between leftsub and rightsub || <nowiki>&#x2666</nowiki>; || Global<br />
|-<br />
| tableBorderRadius || CSS specifier for how rounded the borders of the output card are. Use "0px;" for square borders || 6px; || Global<br />
|-<br />
| tableShadow || CSS specifier for the drop shadow under the output card || 5px 3px 3px 0px #aaa; || Global<br />
|-<br />
| tablebgcolor || Background color of the whole card. '''''Normally not visible''''' || #EEEEEE || Global<br />
|-<br />
| tableborder || Color of the border that surrounds the whole card || 2px solid #000000; || Global<br />
|-<br />
| 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<br />
|-<br />
| timezone || IANA Specifier for the local time zone, used in system/date functions || America/New_York || Per-Line<br />
|-<br />
| title || Text displayed in the title area of the card || ScriptCards || Global<br />
|-<br />
| titleCardBackground || A hex color code representing the background color of the title area. || #1c6ea4 || Global<br />
|-<br />
| titleFontColor || Color of the text on the card title || #FFFFFF || Global<br />
|-<br />
| titleFontFace || Name of the font used on the title area || Contrail One || Global<br />
|-<br />
| titleFontLineHeight || Line spacing on the title area || 1.2em || Global<br />
|-<br />
| titleFontSize || Size of the title font || 1.2em || Global<br />
|-<br />
| titlecardbackgroundimage || Specify an image (content for a CSS background-image tag) for the title card area || none || Global<br />
|-<br />
| titlecardbottomborder || Border CSS specifier for the bottom of the title card area || 2px solid #444444; || Global<br />
|-<br />
| titlecardgradient || If set to non-zero value, will place a vertical gradient on the title card area || 0 || Global<br />
|-<br />
| usehollowdice || If set to a non-zero value, the hollow/outline versions of the dice fonts will be used || 0 || Per-Line<br />
|-<br />
| whisper|| Comma separated list of who to whisper the output to. Use "gm" for [[GM|GMs]] and "self" for the sender || none || Global|}<br />
|}<br />
<br />
''Setting Lines do not produce output lines on the card''<br />
<br />
=== Direct Output (--+) ===<br />
<br />
A direct output line display 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.<br />
<br />
Examples of Direct Output lines:<br />
<pre><br />
--+Hello|World<br />
--+Attack|The monster rolls [$Attack] to hit!<br />
--+Damage|@{target|token_name} is hit for [$Damage] [#3333AA][b]frost[/b][/#] damage.<br />
</pre><br />
<br />
Direct Output lines support inline formatting, roll variable replacement, character attribute references, and procedure variables.<br />
<br />
=== GM Output (--*) ===<br />
<br />
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. <br />
<br />
Example:<br />
<pre><br />
--+PlayerLine|This line is shown on the public card<br />
--*GMLine|This line will only be shown to GMs, on a separate card.<br />
</pre><br />
<br />
=== Roll Variable Assignment (--=) ===<br />
<br />
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.<br />
<br />
'''''All components of a roll equation should be separated with spaces.'''''<br />
<br />
Examples:<br />
<pre><br />
--=MissileDamage|1d4 + 1<br />
--=Attack|1d20 + @{selected|strength_mod} [STR] + @{selected|pb} [PROF]<br />
</pre><br />
<br />
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. Text enclosed in square brackets ([]) is considered "flavor text" and will be added to the result text but does not impact the roll result.<br />
<br />
The following dice formats are supported:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Format Pattern !! Example !! Description<br />
|-<br />
| XdY || 3d8 || Simple format. Roll a Y-sided die X times<br />
|-<br />
| XdYkhZ || 2d20kh1 || Roll Y-sided die X times and keep the highest Z number of dice<br />
|-<br />
| XdYklZ || 4d6kl3 || Roll Y-sided die X times and keep the lowest Z number of dice <br />
|-<br />
| XdY>Z || 5d6>3 || Roll Y-sided die X times and count a 1 for each roll greater than Z <br />
|-<br />
| XdY<Z || 5d6<3 || Roll Y-sided die X times and count a 1 for each roll less than Z <br />
|-<br />
| 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<br />
|-<br />
| 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<br />
|-<br />
| 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)<br />
|-<br />
| 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<br />
|-<br />
| 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).<br />
|-<br />
| 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.<br />
|-<br />
| 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. ('''''v1.5.1''''')<br />
|}<br />
<br />
The following operators are supported in a roll equation:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Operator !! Operation<br />
|-<br />
| + || Addition <br />
|-<br />
| - || Subtraction <br />
|-<br />
| * || Multiplication <br />
|-<br />
| / || Division <br />
|-<br />
| \ || Integer Division (Rounds down) <br />
|-<br />
| % || Modulo (Remainder of Divison)<br />
|}<br />
<br />
Roll Variables can be accessed at any time after they have been created by using the [$VariableName] format, with the following optional modifiers:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Modifier !! Meaning<br />
|-<br />
| No modifier || In a Direct Output Line (<nowiki>--+</nowiki>) 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<br />
|-<br />
| .Total || The end result of the roll equation as an unformatted number <br />
|-<br />
| .Base || The cumulative result of any dice rolled in the Roll Text (Numeric modifiers are not included) <br />
|-<br />
| .Ones || The number of dice in the roll that came up as 1s <br />
|-<br />
| .Aces || The number of dice in the roll that came up as the maximum number on the die <br />
|-<br />
| .Odds || The number of dice in the roll that came up with an odd number <br />
|-<br />
| .Evens || The number of dice in the roll that came up with an even number <br />
|-<br />
| .RollText || The raw text of the roll that was use to generate the results <br />
|-<br />
| .Text || A text representation of the results of the roll, including the numbers rolled for each die <br />
|-<br />
| .tableEntryText || The text portion of the result of a table roll<br />
|-<br />
| .tableEntryImgURL || The image source portion of the result of a table roll<br />
|-<br />
| .tableEntryValue || Numeric value of tableEntryText (via parseInt). If a non-numeric value, will be 0<br />
|-<br />
| .Raw || The total numeric result without any formatting, even if placed somewhere formatting would normally be done. <br />
|}<br />
<br />
Examples:<br />
<pre><br />
--+Total Damage|[$MissileDamage.Total] (roll was 1d4+1)<br />
--+Base Damage|[$MissileDamage.Base] (without the +1)<br />
--=Attack|1d20 + @{selected|strength_mod} [STR] + @{selected|pb} [PROF] + [$BlessBonus] [Bless]<br />
</pre><br />
<br />
In this case, 1d4 will be rolled and stored in “BlessBonus”, which can then be used in the Attack line.<br />
<br />
'''''Mathematical Functions in Roll Expressions '''''<br />
<br />
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:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Expression !! Meaning<br />
|-<br />
| {ABS} || Absolute Value<br />
|-<br />
| {CEIL} || Ceiling value (round up to the next whole number)<br />
|-<br />
| {FLOOR} || Floor value (round down to the next whole number)<br />
|-<br />
| {ROUND} || Round value (round up if the decimal portion is greater than 0.5, otherwise round down) '''Note: As of 1.4.11, ROUND now supports :X as a suffix to round to a given number of decimal places (ie, {ROUND:2}'''<br />
|-<br />
| {NEGATE} || Multiply the value by negative one.<br />
|-<br />
| {SQRT} || Take the square root of the running value.<br />
|-<br />
| {SQUARE} || Square the running value.<br />
|-<br />
| {CUBEROOT} || Take the cube root of the running value.<br />
|-<br />
| {CUBE} || Cube the running value.<br />
|-<br />
| {SIN} || Return the SIN of running value.<br />
|-<br />
| {COS} || Return the COS of running value.<br />
|-<br />
| {TAN} || Return the TAN of running value.<br />
|-<br />
| {ASIN} || Return the ASIN of running value.<br />
|-<br />
| {ACOS} || Return the ACOS of running value.<br />
|-<br />
| {ATAN} || Return the ATAN of running value.<br />
|-<br />
| {MAX:X} || Caps the running value at X. ('''''v1.4.12''''')<br />
|-<br />
| {MIN:X} || If the running value is less than X, set the value to X. ('''''v1.4.12''''')<br />
|-<br />
| {CLAMP:X:Y} || Adjust the running value to remain between X (lower bound) and Y (upper bound) ('''''v1.4.12''''')<br />
|}<br />
<br />
Here are the syntax rules when using the above listed functions:<br />
<br />
Example 1.<br />
<br />
<pre><br />
!script {{<br />
--=output|2.9 {FLOOR}<br />
--+output|[$output]<br />
}}<br />
</pre><br />
<br />
The output from this example is "2".<br />
<br />
Example 2.<br />
<br />
<pre><br />
!script {{<br />
--=output|2.9 {FLOOR} {NEGATE} - 3<br />
--+output|[$output]<br />
}}<br />
</pre><br />
<br />
The output from this example is "-5".<br />
<br />
Basically, a function will use as its input whatever the current "running total" is.<br />
<br />
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.<br />
<br />
<br />
'''''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 <nowiki>[[ ]]</nowiki> 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.<br />
<br />
'''''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.<br />
<br />
'''Rolling on Rollable Tables'''<br />
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.<br />
<br />
''Roll Variable Lines do not produce output lines on the card.''<br />
<br />
=== String Variable Assignment (--&) ===<br />
<br />
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:<br />
<br />
<pre><br />
--&MyText|Hello<br />
</pre><br />
<br />
Here, we assign the text "Hello" to the string variable named MyText. You can also append text to a string variable by prefixing the content with a + sign:<br />
<br />
<pre><br />
--&MyText|+ World<br />
</pre><br />
<br />
If run after the statement above, MyText will now contain "Hello World".<br />
<br />
String variables can be referenced using the syntax [&variablename]<br />
<br />
=== Call API (--@) ===<br />
<br />
ScriptCards can use a Call API instruction to execute other API commands. The Tag contains the API 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 API command is executed.<br />
<br />
Examples:<br />
<pre><br />
--@eh|list<br />
--@alter|_target|@{target|token_id} _bar|3 _amount|-[$Damage]<br />
</pre><br />
<br />
In the first example above, the command <code>!eh list</code> will be executed, calling [[EncounterHelper]]. In the second, {{fpl|1216260/ AlterBars}} is called to modify a token's Bar 3 value.<br />
<br />
'''''Note:''''' When ScriptCards (or any API script) runs other API 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).<br />
<br />
See [[API:Script Index]] for more options.<br />
<br />
=== Branch Label (--:) ===<br />
<br />
A branch label defines a line in your code that can be reached by one of the branching instructions (<nowiki>--^</nowiki>, <nowiki>--></nowiki>, or <nowiki>--?</nowiki>). The Tag serves as the label name, and must be unique on the card.<br />
<br />
The vertical bar (|) separator must be present, but the content portion of the line is unused and can be treated as a comment.<br />
<br />
Examples:<br />
<pre><br />
--:MyLoop|<br />
--:CriticalHit|Will jump here if we roll a critical hit!<br />
</pre><br />
<br />
''A Branch Label line does not produce an output line on the card.''<br />
<br />
=== Branch (--^) === <br />
<br />
A Branch line 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.<br />
<br />
Examples:<br />
<pre><br />
--^MyLoop|Jumps to MyLoop<br />
--^SkipCrit|We didn't crit, so skip the Crit code<br />
</pre><br />
<br />
''A Branch line does not produce an output line on the card.''<br />
<br />
=== Call Procedure (-->) ===<br />
<br />
Similar to a branch, a Call Procedure (sometimes knows 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 (<nowiki>--<</nowiki>) 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 (;).<br />
<br />
Examples:<br />
<pre><br />
-->FixFormat|#3333FF;#999999<br />
</pre><br />
<br />
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%].<br />
<br />
=== Return (--<) ===<br />
<br />
A return instruction marks the end of a Gosub procedure. 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.<br />
<br />
Examples:<br />
<pre><br />
--<|<br />
--<|End of MySub<br />
</pre><br />
<br />
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.<br />
<br />
=== Conditional Statement (--?) ===<br />
<br />
A conditional statement contains some equation in the Tag that will be evaluated. '''''If any part of the comparison can/does contain a space, it needs to be surrounded by double quotes'''''<br />
<br />
Based on the true/false result of the evaluation, one of two execution paths will be taken. These execution paths are detailed in the content section of the statement. The "if true" path is specified first (directly after the vertical bar), and the "if false" path is specified after it, also separated by a vertical bar.<br />
<br />
Example:<br />
<pre><br />
--?[$AttackRoll.Total] -ge [$TargetAC]|Hit|Miss<br />
</pre><br />
<br />
'''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.'''<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Branch Format !! Meaning<br />
|-<br />
| Label || If just a label is specified, execution will branch to that label when the comparison is matched.<br />
|-<br />
| >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 <br />
|-<br />
| =VariableName || The roll variable "VariableName" will be assigned the value following a semicolon (ex: --?1 -eq 1|=Roll;1d20)<br />
|-<br />
| &VariableName || The string variable "VariableName" will be assigned the value following a semicolon (ex: --?1 -eq 1|&Result;Hit|&Result;Miss)<br />
|-<br />
| % or %! || The current for...next loop will perform the "next" action (%) or will break out (%!) <br />
|-<br />
| [ || Code block (see below)<br />
|}<br />
<br />
Examples:<br />
<pre><br />
--?[$AttackRoll.Base] -eq 20|CriticalHit<br />
--?[$AttackRoll.Base] -eq 1|>Fumble;@{selected|dexterity_mod}<br />
--?"@{target|npc_type}" -inc "undead"|&MonsterType;Undead|&MonsterType;Not Undead<br />
--?[$Attack.Total] >= [$ArmorClass]|>Hit|>Miss<br />
</pre><br />
<br />
In the first example, if the Base value of AttackRoll is a 20 (natural 20 on the die) execution will branch to the CriticalHit label.<br />
<br />
In the second example, 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%].<br />
<br />
The third example looks for the word "undead" in the npc_type attribute of the targeted character. If it exists in the text, the MonsterType string variable will be set to "Undead", otherwise it will be set to "Not Undead". <br />
<br />
The final example would call 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.<br />
<br />
''Text that does/may contain a space should be enclosed in double quotes.''<br />
<br />
The following comparison operators are available:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Comparator !! Meaning<br />
|-<br />
| -eq || Equal To <br />
|-<br />
| -eqi || Case insensitive Equal To <br />
|-<br />
| -ne || Not Equal To <br />
|-<br />
| -nei || Case insensitive Not Equal To <br />
|-<br />
| -gt || Greater Than <br />
|-<br />
| -ge || Greater Than or Equal To <br />
|-<br />
| -lt || Less Than <br />
|-<br />
| -le || Less Than or Equal To <br />
|-<br />
| -inc || Includes (text strings). <br />
|-<br />
| -ninc || Does Not Include (text strings). <br />
|}<br />
<br />
Multi-part conditionals are supported with -and and -or as separators. For example:<br />
<br />
<pre><br />
--?[$Attack.Total] -ge @{target|npc_ac} -and [$Attack.Base] -ne 20|HitButNotCrit<br />
</pre><br />
<br />
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):<br />
<br />
true AND false OR true<br />
<br />
Will be evaluated as true. The first two (true and false) will be false, but then false OR true will be true.<br />
<br />
Conversely:<br />
<br />
true or false and false<br />
<br />
Will be false, because the first true and false will evaluate to true, and then true and false will be false.<br />
<br />
'''CODE BLOCKS'''<br />
<br />
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.<br />
<br />
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:<br />
<br />
<pre><br />
!script {{<br />
--=Roll|1d2<br />
--+Roll|[$Roll]<br />
--?[$Roll.Total] -eq 2|[<br />
--&Value|Yep!<br />
--+|We are inside the TRUE portion of the block<br />
--]|[<br />
--&Value|Nope<br />
--+|We are inside the FALSE portion of the block<br />
--]|<br />
--+After|the blocks!<br />
--+Value|[&Value]<br />
}}<br />
</pre><br />
<br />
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 --]|. <br />
<br />
At this time, blocks cannot be nested, and can only be created as part of a conditional (--[ is not a valid statement type)<br />
<br />
''A conditional statement does not produce a line of output on the card.''<br />
<br />
=== Case Statement (--c) ===<br />
<br />
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 (:). Each match condition includes a branch label that will be used if the test value matches the item. 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:<br />
<br />
<pre><br />
!script {{<br />
--#title|Case Statement Testing<br />
--=Roll|1d4<br />
--C[$Roll.Total]|1:>One;[$Roll]|2:>Two;[$Roll]|3:>Three;[$Roll]|4:>Four;[$Roll]<br />
--X|<br />
<br />
--:One| --+Value|was One ([%1%]) --<|<br />
--:Two| --+Value|was Two ([%1%]) --<|<br />
--:Three| --+Value|was Three ([%1%]) --<|<br />
--:Four| --+Value|was Four ([%1%]) --<|<br />
}}<br />
</pre><br />
<br />
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 variable as a parameter.<br />
<br />
=== Save and Load (--s and --l) ===<br />
<br />
This statement pair is used to either store (--s) or load (--l) data from persistent storage. Items stored in persistent storage remain between card rolls and between Roll20 sessions. There are two types of data that can be stored: settings and roll variables. <br />
<br />
Examples:<br />
<br />
<pre><br />
--Ssettings|GreenStyle<br />
--Srollvariables|FirstCardVars<br />
</pre><br />
<br />
In this case, the tag for the statement determines what type of item is being saved (settings or rollvariables). When saving settings, all non-default settings are written to the named setting storage value. When Roll Variables are saved, all variables that currently exist will be saved to the named storage value.<br />
<br />
Loading stored items simply requires the same command with the --l statement type:<br />
<br />
<pre><br />
--Lsettings|GreenStyle<br />
--Lrollvariables|FirstCardVars<br />
</pre><br />
<br />
When loading settings, all stored settings will be applied to the current card settings. You can override settings by changing them after the load.<br />
<br />
When loading roll variables, the saved variables will be added to (or overwrite if they have the same name) any variables on the current card. This means it is safe to create roll variables before the load statement.<br />
<br />
'''Practical Uses'''<br />
The major intended use of persistent storage is for storing card formats for use in later scripts. For example, the following script:<br />
<br />
<pre><br />
!scriptcard {{<br />
--#titlecardbackground|#22CC22<br />
--#oddrowbackground|#cceecc<br />
--#evenrowbackground|#99ee99<br />
--Ssettings|@{selected|token_name}<br />
}}<br />
</pre><br />
<br />
Would save the titlecardbackground, oddrowbackground, and evenrowbackground settings to a saved list named after the selected token's name. When creating cards for that token to run later, you could include the line:<br />
<br />
<pre><br />
--Lsettings|@{selected|token_name}<br />
</pre><br />
<br />
To load all of the settings at once. By creating these setting sets for each character, you can specify a different color scheme for each character that can then be used in cards with a single formatting line.<br />
<br />
There is a supplemental ! command added to support saved settings:<br />
<br />
<pre><br />
!sc-liststoredsettings<br />
</pre><br />
<br />
Will produce a list of all stored setting names, with buttons to list the setting values stored in each group and a button to delete groups as needed.<br />
<br />
=== Visual Effects (--v) ===<br />
<br />
The --v statement can be used to create visual effects on the tabletop. The tag portion of the statement can be either "token" or "betweentokens". The content portion of the statement contains the required parameters for the effect generation, separated by spaces. If the effect is "none", no effect will be played. If any other value that doesn't match a Roll20 effect name will result in a burst-fire effect.<br />
<br />
For "token" effects, the parameters are the token id for the token the effect happens on, followed by the effect specifier.<br />
<br />
Example:<br />
<pre><br />
--vtoken|@{selected|token_id} burst-fire<br />
</pre><br />
<br />
For "betweentoken" effects, the parameters are the source token id, the target token id, and the effect specifier.<br />
<br />
Example:<br />
<pre><br />
--vbetweentokens|@{selected|token_id} @{target|token_id} beam-magic<br />
</pre><br />
<br />
'''''Version 1.2.8+'''''<br />
<br />
An additional effect specifier, "point" is available in 1.2.8+. This specifier allows you to create a visual effect at a designated X/Y pixel coordinate. Future updates will add custom-vfx support to this option. The parameters are the X and Y coordinates and the effect descriptor. As of version 1.2.9, you can also use custom effect specifiers with Point effects:<br />
<br />
<pre><br />
--vpoint|150 200 burst-fire<br />
</pre><br />
<br />
=== Audio Effects (--a) ===<br />
<br />
'''''Requires version 1.5.2+'''''<br />
<br />
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.<br />
<br />
<pre><br />
--a|SwordHitSound<br />
</pre><br />
<br />
No external APIs are required.<br />
<br />
=== Echo to Chat (--e) ===<br />
<br />
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.<br />
<br />
Example:<br />
<pre><br />
--eThe Ghost|/em hovers around @{selected|character_name}... BOO!<br />
</pre><br />
<br />
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).<br />
<br />
'''''Whispering'''''<br />
<br />
You can use the echo statement to send a whisper, but there's a trick to it. If you execute this code here:<br />
<br />
<pre><br />
--eThe Ghost|/w ExamplePlayerName Boo.<br />
</pre><br />
<br />
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.<br />
<br />
So, in conclusion, it's best to use something like this when you're sending a whisper:<br />
<br />
<pre><br />
!script {{<br />
--#hidecard|1<br />
--&sender|The Ghost<br />
--&receiver|ExamplePlayerName<br />
--&message|Boo.<br />
--e[&sender]|/w [&receiver] [&message]<br />
--eScriptCards|/w gm **Whispered from [&sender] to [&receiver]:** [&message] <br />
}}<br />
</pre><br />
<br />
This will ensure that the message appears in your chat feed as well.<br />
<br />
=== Repeating Section Access (--R) ===<br />
<br />
ScriptCards (as of v0.0.13) supports accessing repeating section rows on a character sheet (for example: the attacks, the items, and the repeating resources) with the --R statement type. <br />
<br />
There are three basic commands you can use with --R, and they are specified by <br />
the tag used:<br />
<br />
<br />
'''''The "find" tag'''''<br />
<br />
An Rfind statement is used to search through a repeating field. Here is the general form of such a statement.<br />
<br />
<pre><br />
--Rfind|characterid;EntryName;SectionPrefix;SearchField<br />
</pre><br />
<br />
This is the most direct way to access a repeating section row. Supplying the character ID, followed by what you are looking for (Greatsword, for example), followed by the character sheet's section prefix (repeating_attack), followed by the field to check what you are searching for (atkname) will load the matching section (if found) into the script parsers memory. For example:<br />
<br />
<pre><br />
--Rfind|@{selected|character_id};Greatsword;repeating_attack;atkname<br />
</pre><br />
<br />
Will look at the character's "repeating_attack" section for an entry with an atkname value equal to "Greatsword". Similarly:<br />
<br />
<pre><br />
--Rfind|@{selected|character_id};Bite;repeating_npcaction;name<br />
</pre><br />
<br />
Will look for a "Bite" action on an NPC's action list.<br />
<br />
<br />
'''''The "first" tag'''''<br />
<br />
<pre><br />
--Rfirst|characterid;section prefix<br />
</pre><br />
<br />
This form of the --R command will look at all of the entries in the specified repeating section and load the first one into memory:<br />
<br />
<pre><br />
--Rfirst|@{selected|character_id};repeating_attack<br />
</pre><br />
<br />
Would load the character's first "repeating_attack" row into memory.<br />
<br />
<br />
'''''The "next" tag'''''<br />
<br />
<pre><br />
--Rnext|<br />
</pre><br />
<br />
No parameters are required for --Rnext, which loads the next entry in the list that was obtained with "first" into memory.<br />
<br />
<br />
'''''Section prefixes and how to use them'''''<br />
<br />
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 open [[D&D 5E by Roll20|this page]], and search for the phrase "repeating sections".<br />
<br />
<br />
'''''Additional information'''''<br />
<br />
However a row is obtained, it will be parsed to replace any attribute references (ie, @{level}) with the corresponding character attribute.<br />
<br />
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".<br />
<br />
You can reference repeating attribute data using the syntax [*R:attributename] syntax (similar to referencing standard character attributes).<br />
<br />
Here are some examples:<br />
<br />
Display the details of the "Greatsword" PC attack:<br />
<br />
<pre><br />
!script {{<br />
--Rfind|@{selected|character_id};Greatsword;repeating_attack;atkname<br />
--+Attack Name|[*R:atkname]<br />
--+Base Damage|[*R:dmgbase]<br />
}}<br />
</pre><br />
<br />
[[File:Scriptcards repeating greatsword.png|Repeating Greatsword Attack]]<br />
<br />
List all of the actions an NPC can take (just actions, not legendary, etc.)<br />
<br />
<pre><br />
!script {{<br />
--#title|NPC Actions<br />
--#leftsub|@{selected|token_name}<br />
--Rfirst|@{selected|character_id};repeating_npcaction<br />
--:DisplayLoop|<br />
--?"[*R:name]" -eq NoRepeatingAttributeLoaded|Done<br />
--+Action:|[*R:name] [*R:attack_damage] [*R:attack_damagetype]<br />
--?"[*R:attack_damage2]" -eq ""|NoSecondaryDamage<br />
--+ |[*R:attack_damage2] [*R:attack_damagetype2]<br />
--:NoSecondaryDamage|<br />
--Rnext|<br />
-->DisplayLoop| <br />
--:Done|<br />
}}<br />
</pre><br />
<br />
[[File:Scriptcards repeating npcactions.png]]<br />
<br />
In the script above, we get the "first" repeating_npcaction and display information about it. We then execute "next" and repeat until we run into "NoRepeatingAttributeLoaded".<br />
<br />
See the section named [[#Repeating Section Values|Repeating Section Values]] for more information.<br />
<br />
<br />
'''''Special debugging command: dump'''''<br />
<pre><br />
--Rdump|<br />
</pre><br />
<br />
The "dump" command will list all of the attributes ScriptCards knows about for the currently loaded repeating row to the API Console Log.<br />
<br />
=== Assign Variable to Built-In Function (--~) ===<br />
<br />
ScriptCards has the ability to run a function built into the API script and return the results to a variable. Some functions return roll variables, while others return strings. See the function table below for details. The format is:<br />
<br />
--~VariableName|function;param1;param2;param3;...<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Function Name !! Parameters !! Description<br />
|-<br />
| distance || token_A_ID;token_B_ID || Calculate the Chebyshev distance in grid units between two tokens. This is the measurement scheme D&D 4E/5E use for diagonal distance measurement<br />
|-<br />
| euclideandistance || token_A_ID;token_B_ID || Calculate the Euclidean distance between two tokens. This is essentially the Pythagorean theorem in action. Returns the result in grid units.<br />
|-<br />
| euclideanpixel || token_A_ID;token_B_ID || Calculate the Euclidean distance between two tokens and returns the result is pixels instead of grid units. <br />
|-<br />
| euclideanlong || token_A_ID;token_B_ID || 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 is calculated instead of before. More accurate over long distances. <br />
|-<br />
| manhattandistance || token_A_ID;token_B_ID || Also called "taxicabdistance" (which is an acceptable function name), this measures to how-many-over, how-many-up/down distance, disallowing diagonal movement.<br />
|-<br />
| getselected || none || 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 the first selected token, VariableName2 the second, etc.<br />
|}<br />
<br />
'''''Functions with Sub Functions'''''<br />
<br />
Most ScriptCards functions are grouped into set as sub functions. The table below lists the major functions and their sub functions.<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Function Name !! Sub Function !! Parameters !! Return Type !! Description<br />
|-<br />
| array || define || arrayname;value1;value2;... || none || Creates an array called "arrayname" and adds value1, value2, etc. to the array<br />
|-<br />
| array || sort || arrayname || none || Sorts the specified array in place in ascending order (alphabetically)<br />
|-<br />
| array || numericsort || arrayname || none || Sorts the specified array in place in ascending order (numerically) ('''''v 1.4.10+ ''''')<br />
|-<br />
| array || add || arrayname;value1;value2;... || none || Adds value1, value2, ... to the existing array "arrayname"<br />
|-<br />
| array || remove || arrayname;value1;value2;... || none || Removes value1, value2, ... from the existing array "arrayname". Resets the array index to 0.<br />
|-<br />
| array || replace || arrayname;currentvalue;newvalue || none || Replaces all occurrences of "currentvalue" in "arayname" with "newvalue"<br />
|-<br />
| array || setatindex || arrayname;index;newvalue || none || Replaces the array item at index "index" with "newvalue"<br />
|-<br />
| array || getindex || arrayname || stringVariable || Retrieves the current index in "arrayname" and stores it in the supplied string variable<br />
|-<br />
| array || setindex || arrayname;newindex || none || Sets the current index in array "arrayname" to "newindex"<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| array || removeat || arrayname;indexposition || none || Removes the item at index "indexposition" from "arrayname". Resets the current array index to 0.<br />
|-<br />
| array || indexof || arrayname;searchvalue || stringVariable || Searches the array "arrayname" for and item with the value of "searchvalue" and, if found, returns the index of the first matching value or "ArrayError" if not found<br />
|-<br />
| array || getlength || arrayname || stringVariable || Returns the number of items in array "arrayname"<br />
|-<br />
| array || pagetokens || arrayname;tokenid;(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. 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.)<br />
|-<br />
| 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.<br />
|-<br />
| array || stringify || arrayname || stringVariable || Returns all of the items in "arrayname" as a string separated by semicolons (;)<br />
|-<br />
| array || fromstring || arrayname || delimiter;string || Creates an array from "string", splitting "string" on "delimiter" to separate the items<br />
|-<br />
| array || statusmarkers|| arrayname;tokenid || none|| Creates an array (arrayname) of the active statusmarkers (sometimes called Token Markers) for the specified tokenid<br />
|-<br />
| math || angle || math;angle;tokenid;tokenid|| rollVariable || Calculates the angle between two tokens and returns the value in degrees<br />
|-<br />
| math || ceil || math;ceil;value || rollVariable || Rounds '''value''' up to the next integer, dropping any decimal portion of the number<br />
|-<br />
| math || clamp || math;clamp;value;lowerBound;upperBound || rollVariable || Returns '''value''', but restricted to the range of '''loweBound''' and '''upperBound'''.<br />
|-<br />
| math || floor || math;floor;value || rollVariable || Rounds '''value''' down, dropping any decimal portion of the number<br />
|-<br />
| math || max || math;max;valueA;valueB || rollVariable || Returns the larger of '''valueA''' vs '''valueB'''<br />
|-<br />
| math || min || math;min;valueA;valueB || rollVariable || Returns the smaller of '''valueA''' vs '''valueB'''<br />
|-<br />
| math || round || math;round;value || rollVariable || Rounds '''value''' to the nearest integer<br />
|-<br />
| string || length || string;length;stringValue || rollVariable || Returns the length of '''stringValue''' in characters<br />
|-<br />
| string || before || string;before;searchText;stringValue || stringVariable || Searches '''stringValue''' for '''searchText''' and returns the portion of '''stringValue''' prior to that text<br />
|-<br />
| string || after || string;after;searchText;stringValue || stringVariable || Searches '''stringValue''' for '''searchText''' and returns the portion of '''stringValue''' after that text<br />
|-<br />
| string || left || string;left;count;stringValue || stringVariable || Returns the leftmost '''count''' characters of '''stringValue'''<br />
|-<br />
| string || right || string;right;count;stringValue || stringVariable || Returns the rightmost '''count''' characters of '''stringValue'''<br />
|-<br />
| string || replace || string;replace;searchText;replaceText;stringValue || stringVariable || Replaces '''searchText''' in '''stringValue''' with '''replaceText''' and returns the resulting string<br />
|-<br />
| string || replaceall || string;replace;searchText;replaceText;stringValue || stringVariable || Replaces all intances of '''searchText''' in '''stringValue''' with '''replaceText''' and returns the resulting string '''''Requires 1.2.9+'''''<br />
|-<br />
| string || trim || string;trim;stringValue || stringVariable || Removes leading and trailing spaces from stringValue and returns the result. <br />
|-<br />
| string || substring || string;substring;start;count;stringValue || stringVariable || Returns '''count''' characters starting at '''start''' from '''stringValue'''<br />
|-<br />
| 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.<br />
|-<br />
| string || tolowercase || string;tolowercase;stringValue || stringVariable || Converts the passed string to lower case and assigns to the passed variable name. <br />
|-<br />
| string || touppercase || string || stringVariable || Converts the passed string to upper case and assigns to the passed variable name. <br />
|-<br />
| 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. <br />
|-<br />
| 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.<br />
|-<br />
| 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'''.<br />
|-<br />
| turnorder || clear || none || none || Clears all entries from the {{Turn Tracker}}/Initiative<br />
|-<br />
| turnorder || addtoken || tokenid;trackervalue || none || Adds the token represented by "tokenid" to the initiative tracker with an initiavie value of "trackervalue"<br />
|-<br />
| turnorder || replacetoken || tokenid;trackervalue || none || Replaces the token represented by "tokenid" in the initiative tracker with an initiavie value of "trackervalue". Will add the token if it doesn't exist in the tracker.<br />
|-<br />
| turnorder || removetoken || tokenid || none || Removes the token represented by "tokenid" from the initiative tracker if it exists<br />
|-<br />
| turnorder || addcustom || textlabel;trackervalue || none || Add a custom text entry to the {{Turn Tracker}}/Initiative named "textlabel" with an initiative value of "trackervalue"<br />
|-<br />
| system || date || getdatetime || stringVariable || Returns the date time in the active timezone (see settings) <br />
|-<br />
| system || date || getdate || stringVariable || Returns the date in the active timezone (see settings) <br />
|-<br />
| system || date || gettime || stringVariable || Returns the time in the active timezone (see settings)<br />
|-<br />
| system || dumpvariables || "rolls", "string", or "array" || none || Dumps all of the defined variables of the indicated type to the console log<br />
|-<br />
| system || findability || system;findability;charactername;abilityname || stringVariable || Returns the object ID of the ability on the indicated character or "AbilityNotFound"<br />
|-<br />
|}<br />
<br />
Examples:<br />
<br />
<pre><br />
--~HowFarAway|distance;@{selected|token_id};@{target|token_id}<br />
</pre><br />
<br />
Returns the distance (Chebyshev) between the selected and target tokens and stores it in "HowFarAway".<br />
<br />
<pre><br />
--SelectedDudes|getselected<br />
</pre><br />
<br />
If 5 tokens were selected, 6 variables would be created: SelectedDudesCount (with a value of 5), SelectedDudes1, SelectedDudes2, SelectedDudes3, SelectedDudes4, SelectedDudes5.<br />
<br />
=== Information Request (--i) ===<br />
<br />
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.<br />
<br />
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.<br />
<br />
After the user has clicked the button and responded to the requests, ScriptCards will resume processing the script from where it left off.<br />
<br />
Here is an example “i” line:<br />
<br />
<pre><br />
--IScriptCards needs additional information to continue;Click to select a target and provide information|t;MyNewTarget;Missile1Target||q;MyNameIs;What is your name?<br />
</pre><br />
<br />
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.<br />
<br />
Supported information request types are “t” for target token, and “q” for query.<br />
<br />
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).<br />
<br />
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:<br />
<br />
<pre><br />
q;UserName;What is your name?|Fred|Bob|Sally|Nancy<br />
</pre><br />
<br />
Would have a dropdown menu with four choices.<br />
<br />
=== Object Modification (--!) ===<br />
<br />
'''''Requires ScriptCards version 1.5.0+'''''<br />
<br />
Object modification support is now available in ScriptCards. As of 1.5.0, you can use the --! command to modify object properties in the game. This may help reduce the reliance on the --@ command to run other API commands to modify token/character values. The biggest benefit of this is that the changes happen as the script is processing, so the new values are available right away. <br />
<br />
The format of the command is:<br />
<pre><br />
--!<objectType>:<objectId>|setting:value|setting:value|setting:value...<br />
</pre><br />
<br />
'''objectType''' can be one of "t" for token, "c" for character, or "a" for character attribute<br />
<br />
'''objectId''' can be a token id or a character id (or "S"/"T" for the Source/Target token/char defined with --#sourcetoken and --#targettoken)<br />
<br />
'''setting''' and '''value''' pairs can be chained in a single statement separated by | to impact more than one property/attribute with a single line<br />
<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
Examples:<br />
<br />
Set the value of bar1_value for the selected token to 5:<br />
<pre> --!t:@{selected|token_id}|bar1_value:5</pre><br />
Add 1 to the bar3_value for the selected token:<br />
<br />
<pre> --!t:@{selected|token_id}|bar3_value:+=1</pre><br />
Set bar2_value to 5 and bar2_max to 10 for the selecte token<br />
<br />
<pre> --!t:@{selected|token_id}|bar2_value:5|bar2_max:10</pre><br />
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:<br />
<br />
<pre> --!a:@{selected|token_id}|dndstyling:on|size:enormous|!attitude:epic</pre><br />
Adds 50 to the npc_xp attribute for the character represented by the selected token, displaying the value before and after the update:<br />
<br />
<pre><br />
!script {{<br />
--+XP|[*@{selected|token_id}:npc_xp]<br />
--!a:@{selected|token_id}|npc_xp:+=50<br />
--+XP|[*@{selected|token_id}:npc_xp]<br />
}}<br />
</pre><br />
<br />
Note that asynchronous read/update fields (bio, notes, gmnotes) are not currently supported.<br />
<br />
== Inline Formatting ==<br />
<br />
Inline formatting is processed on Direct Output lines only (--+ lines) and the following inline format markup is available:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Formatting Tags !! Description<br />
|-<br />
| [b]..[/b] || Bold the text between the markers <br />
|-<br />
| [i]..[/i] || Italicize the text between the markers <br />
|-<br />
| [u]..[/u] || Underline the text between the markers <br />
|-<br />
| [s]..[/s] || Strike-Thru the text between the markers <br />
|-<br />
| [c]..[/c] || Center alignment <br />
|-<br />
| [l]..[/l] || Left alignment <br />
|-<br />
| [r]..[/r] || Right alignment <br />
|-<br />
| [j]..[/j] || Full justification alignment <br />
|-<br />
| [#xxx]..[/#] or [#xxxxxx]..[/#] || Use a 3 or 6 digit hex code to colorize the text between the markers <br />
|-<br />
| [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, <code>[img width=128 height=128]</code> )<br />
|-<br />
| [button]caption::action[/button] || Create a button with the label "caption" that performs the action defined by "action". By default, buttons will be colored according the the buttontextcolor and buttonbackground card settings. You can optionally color individual buttons by specifying a text color and a background color as part of the [button] command (ie, [button:#ffffff:#000000] will create a button with white text on a black background. In order to set a background color, the foreground color must be specified.<br />
|-<br />
| [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. By default, buttons will be colored according the the buttontextcolor and buttonbackground card settings. You can optionally color individual buttons by specifying a text color and a background color as part of the [sheetbutton] command (ie, [sheetbutton:#ffffff:#000000] will create a button with white text on a black background. In order to set a background color, the foreground color must be specified.<br />
|-<br />
| [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. By default, buttons will be colored according the the buttontextcolor and buttonbackground card settings. You can optionally color individual buttons by specifying a text color and a background color as part of the [rbutton] command (ie, [rbutton:#ffffff:#000000] will create a button with white text on a black background. In order to set a background color, the foreground color must be specified.<br />
|-<br />
| [t] || Converted to HTML table tag. Text after the "t" will be included inside the tag (width, border, etc)<br />
|-<br />
| [/t] || Converted to HTML close table tag.<br />
|-<br />
| [tr] || Converted to HTML table row tag. Text after the "tr" will be included inside the tag<br />
|-<br />
| [/tr] || Converted to HTML close table row tag.<br />
|-<br />
| [td] || Converted to HTML table cell tag. Text after the "tr" will be included inside the tag<br />
|-<br />
| [/td] || Converted to HTML close table cell tag.<br />
|}<br />
<br />
Code Example<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Formatting Tags !! Description<br />
|-<br />
| <pre>!script {{<br />
--#title|Inline Formatting Examples<br />
--+|This text [b]is bolded[/b]<br />
--+|This text [i]is italicized[/i]<br />
--+|This text [u]is underlined[/u]<br />
--+Alignment|[l]Left[/l]<br />
--+|[c]Center[/c]<br />
--+|[r]Right[/r]<br />
--+|[j]This long bit of text is justified to fit smoothly into the display area for the card with justified wrapping.[/j]<br />
--+Colorized|[#f00]Red[/#] [#0f0]Green[/#] [#00f]Blue[/#]<br />
--+Button|[button]Do Something::DoOnClick[/button]<br />
--+Button Colors|[button:#000:#f00]Red::RedClick[/button] [button:#000:#0f0]Blue::BlueClick[/button] [button:#000:#00f]Blue::BlueClick[/button]<br />
--+Table:|<br />
--+|[t border=2 width=100%][tr][td]Cell1[/td][td]Cell2[/td][/tr][tr][td]Cell3[/td][td]Cell4[/td][/tr][/t]<br />
}}</pre> || [[File:Sc-formatting_example.png]]<br />
|}<br />
<br />
== Variables ==<br />
<br />
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. While it is possible to assign both a string and a roll variable the same name, doing so will likely result in confusion when looking at the script later, so it is not recommended.<br />
<br />
String Variables are assigned with the --& statement and are referenced using [&variableName] notation.<br />
<br />
Roll Variables are assigned with the --= statement, and the assignment value is always processed by the ScriptCards Roll Processor (resolves dice rolls, etc.)<br />
<br />
There are a handful of variables assigned automatically when a ScriptCard is executed. These are all string variables, and are:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Variable !! Value<br />
|-<br />
| SendingPlayerID || Contains the object ID of the player that sent the macro<br />
|-<br />
| SendingPlayerName || Contains the display name of the player<br />
|-<br />
| SendingPlayerColor || Contains the color code associated with the player<br />
|-<br />
| SendingPlayerSpeakingAs || The contents of the "Speaking As" dropdown window<br />
|-<br />
| SendingPlayerIsGM || Contains 1 if the player is a GM, and 0 if the player is NOT a GM<br />
|}<br />
<br />
== Arrays ==<br />
<br />
Arrays are a special type of variable, and are managed by the function (<nowiki>--~</nowiki> command). All of the array function commands follow the same pattern:<br />
<br />
<pre>--~variableName|array;subcommand;arrayname;param1;param2;param3;...</pre><br />
<br />
Not all array commands return anything to "variableName". The function table above will specify the return type of the command if any.<br />
<br />
There are a couple of different ways to create an array:<br />
<br />
The '''define''' array subcommand creates (or recreates) an array and assigns it values - one for each included parameter after the array name. For example:<br />
<br />
<pre>--~|array;define;Fruits;mango;peach;strawberry;apricot;banana;apple</pre><br />
<br />
will create an array called '''Fruits''' with 6 elements in the order listed in the command (mango, peach, etc.)<br />
<br />
You can also use two other subcommands to create arrays based on tokens:<br />
<br />
<pre>--~Count|array;pagetokens;Everybondy;@{selected|token_id}</pre><br />
<br />
and<br />
<br />
<pre>--~Count|array;selectedtokens;Selected</pre><br />
<br />
In both cases, arrays of tokens will be created, and a string variable called "Count" will be set to the number of tokens in the array. The '''pagetokens''' command returns (by default) all of the tokens on the page that contains the token passed as the parameter after the array name. You can filter the tokens that "pagetokens" includes in the array by appending an optional parameter describing the type of token you are looking for:<br />
<br />
<pre>--~Count|array;pagetokens;Everybondy;@{selected|token_id};npc</pre><br />
<br />
Will return only tokens on the page that represent characters that do not have a ''controlledby'' parameter set. The available options are "all" (default), "char", "graphic", "pc", and "npc".<br />
<br />
The '''selectedtokens''' command returns an array with all of the tokens that were selected when the script was called.<br />
<br />
You can also use an arbitrary string to create an array, specifying a delimiter with the '''fromstring''' command:<br />
<br />
<pre><br />
--&names|Fred<br />
--&names|+,Sally<br />
--&names|+,Ted<br />
--&names|+,Joyce<br />
--~|array;fromstring;,;[&names]<br />
</pre><br />
<br />
The above example builds a comma-separated string and then uses "fromstring" to create an array with 4 elements from it, specifying the comma as the delimiter.<br />
<br />
Finally, you can use the '''statusmarkers''' command to create an array with one entry for each active status marker on a specified token:<br />
<br />
<pre>--~|array;statusmarkers;Conditions;@{selected|token_id}</pre><br />
<br />
will create an array with one entry for each status active on the selected token. The array elements will be the internal name of the status (if you are using custom status marker packs, the names will be specified in the marker pack).<br />
<br />
'''Traversing Arrays'''<br />
<br />
Each array keeps track of an internal index position (starting at 0). Several commands let you manage this index:<br />
<br />
*'''getindex''' returns the current index value<br />
*'''setindex''' sets the index to the specified location in the array<br />
*'''getlength''' returns the number of elements in the array<br />
*'''indexof''' returns the index location of the specified element<br />
<br />
Other commands let you retrieve values from the array:<br />
<br />
*'''getfirst''' sets the index to 0 and returns the value at that position<br />
*'''getnext''' advances the index by 1 and returns the new current value<br />
*'''getprevious''' reduces the index by 1 and returns the new current value<br />
*'''getlast''' sets the index to the last elements in the array and returns the new current value<br />
<br />
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.<br />
<br />
'''Manipulating Array Elements'''<br />
<br />
Several array commands deal with inserting, removing, and modifying elements:<br />
<br />
*'''add''' works just like define, except that it takes an existing array and adds elements to it based on the passed parameters<br />
*'''remove''' looks for items matching each passed parameter and removes them from the indicated array if they exist<br />
*'''removeat''' allows you to specify an index location in the array and remove the element at that position<br />
*'''replace''' searches an array for a value and replaces all occurrences of it with a new value (if found)<br />
*'''sort''' sorts the elements in the array in ascending order<br />
*'''strinfigy''' returns a string variable that includes each array element separated by semicolons (;) <br />
<br />
'''Referencing Array Elements'''<br />
<br />
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.<br />
<br />
<pre><br />
!script {{<br />
--~dummy|array;pagetokens;myarray;@{selected|token_id}<br />
--~count|array;getcount;myarray<br />
--+Total:|There are [&count] graphical objects on the page<br />
--~testvar|array;getfirst;myarray<br />
--:loop|<br />
--+Value|[*[&testvar]:character_name]<br />
--~testvar|array;getnext;myarray<br />
--?[&testvar] -ne ArrayError|loop<br />
--+Loop1|Is Done!<br />
}}<br />
</pre><br />
<br />
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:<br />
<br />
<pre><br />
!script {{<br />
--~dummy|array;pagetokens;myarray;@{selected|token_id}<br />
--~count|array;getcount;myarray<br />
--+Total:|There are [&count] graphical objects on the page<br />
--%loopCounter|1;[&count]<br />
--+Value|[*[@myarray([&loopCounter])]:character_name]<br />
--%|<br />
--+Loop|Is Done!<br />
}}<br />
</pre><br />
<br />
This line : <nowiki>--+Value|[*[@myarray([&loopCounter])]:character_name]</nowiki> uses [@arrayName(index)] format (inside a [*characterid:attribute] syntax) to perform the same task as running through the loop with the index.<br />
<br />
(Note: Additional examples are on the way...)<br />
<br />
== For...Next Loops ==<br />
<br />
For...Next loops in ScriptCards are supported with the with the --% statement type. A loop is defined by starting off with:<br />
<br />
<pre><br />
--%LoopCounter|<start>;<end>;[step]<br />
</pre><br />
<br />
The start and end values are required, while the step parameter is optional. If the step is omitted, it will be assumed to be 1. A string variable named after the line tag ("LoopCounter" in the case above) will be created and will hold the current iteration value for the loop. Here is a real example:<br />
<br />
<pre><br />
--%LoopCounter|1;10;1<br />
</pre><br />
<br />
This will begin a loop identified by "LoopCounter" that will start at 1, increasing by 1 each iteration (the step) until it has completed 10 executions.<br />
<br />
The "next" statement is simply <code>--%|</code>, with no tag or parameters. This indicates to ScriptCards that it should increment the counter and go back to the beginning of the loop. Extending the example above:<br />
<br />
<pre><br />
!script {{<br />
--%LoopCounter|1;10;1<br />
--=Roll|1d20<br />
--+Loop|Counter is [&LoopCounter], roll was [$Roll]<br />
--%|<br />
}}<br />
</pre><br />
<br />
The <code>--%!|</code> sequence will break out of the loop, no matter how many iterations are remaining.<br />
<br />
The % and %! character sequences can also be used as part of a 1.2.1+ non-branching conditional to continue or break the loop:<br />
<br />
<pre><br />
--?"X[&RollInto]X" -eq "XX"|%<br />
</pre><br />
<br />
In this example, if the string variable RollInfo is empty, the loop will return to the top and continue with the next iteration, while:<br />
<br />
<pre><br />
--?"X[&RollInto]X" -eq "XX"|%!<br />
</pre><br />
<br />
Would cause the whole loop to end if the condition were true.<br />
<br />
== Referencing ==<br />
<br />
=== Roll Variables===<br />
<br />
Roll Variables can be referenced from the content portion of any line type, and from the tag portion of conditional statements. The referenced value is replaced when the line is executed.<br />
<br />
There are several modifiers that can be used to reference parts of a roll:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Modifier !! Meaning<br />
|-<br />
| No modifier || In a Direct Output Line (<nowiki>--+</nowiki>), GM Output Line (<nowiki>--*</nowiki>), or String Assignement (<nowiki>--&</nowiki>), 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<br />
|-<br />
| .Total || The end result of the roll equation. Formatting rules for "No Modifier" apply based on line type. <br />
|-<br />
| .Raw || The total value of the roll variable without any formatting, no matter what kind of line the reference is used in.<br />
|-<br />
| .Base || The cumulative result of any dice rolled in the Roll Text (Numeric modifiers are not included) <br />
|-<br />
| .Ones || The number of dice in the roll that came up as 1s <br />
|-<br />
| .Aces || The number of dice in the roll that came up as the maximum number on the die <br />
|-<br />
| .Odds || The number of dice in the roll that came up with an odd number <br />
|-<br />
| .Evens || The number of dice in the roll that came up with an even number <br />
|-<br />
| .RollText || The raw text of the roll that was use to generate the results <br />
|-<br />
| .Text || A text representation of the results of the roll, including the numbers rolled for each die <br />
|-<br />
| .tableEntryText || The text portion of the result of a table roll<br />
|-<br />
| .tableEntryImgURL || The image source portion of the result of a table roll<br />
|-<br />
| .tableEntryValue || If the tableEntryText is purely numeric, will contain the numeric value<br />
|}<br />
<br />
=== String Variables ===<br />
<br />
To reference a string variable, use the notation [&variablename]. String variables can be referenced in direct output, roll variable assignment, and string variable assignment statements.<br />
<br />
=== Character/Token Attributes ===<br />
<br />
A character or token attribute can be referenced from content portion of any type of line and is substituted when the line is executed. The general format for referencing a character attribute is [*ID:attribute]. ID can be a token ID or a character ID (these start with a dash). Additionally if you have specified a sourceToken or targetToken, you can substitute "S" or "T" for the ID (for example [*S:npc_type] will retrieve the npc_type attribute from the source token.<br />
<br />
By default, all attribute references will be pulled from the '''''character''''' object that the ID represents (either directly or by being a Token ID that represents a character).<br />
<br />
Keep in mind, that if you want to access the "max" of a character attribute (for example, the max hit points), then you cannot trust the name that your roll20 character sheet shows you when you hover your mouse over the max hit points. For example, this reference will not work: [*S:hp_max]. Instead, you need to use this reference: [*S:hp^].<br />
<br />
If your ID refers to a token, token attributes can be accessed by preceding the attribute name with "t-", for example [*S:t-aura1_radius]. Supported token attributes are:<br />
<br />
{|<br />
| t-name || t-id || t-statusmarkers || t-bar1_value<br />
|-<br />
| t-bar1_max || t-bar2_value || t-bar2_max || t-bar3_value<br />
|-<br />
| t-bar3_max || t-top || t-left || t-width<br />
|-<br />
| t-height || t-rotation || t-layer || t-aura1_radius<br />
|-<br />
| t-aura1_color || t-aura2_radius || t-aura2_color || t-aura1_square<br />
|-<br />
| t-aura2_square || t-tint_color || t-light_radius || t-light_dimradius<br />
|-<br />
| t-light_angle || t-light_losangle || t-light_multiplier || t-light_otherplayers<br />
|-<br />
| t-light_hassight || t-flipv || t-fliph || t-controlledby<br />
|-<br />
| t-_cardid || t-_pageid || t-imgsrc || t-bar1_link<br />
|-<br />
| t-bar2_link || t-bar3_link || t-represents || t-layer<br />
|-<br />
| t-isdrawing || t-name || t-gmnotes || t-showname<br />
|-<br />
| t-showplayers_name || t-showplayers_bar1 || t-showplayers_bar2 || t-showplayers_bar3<br />
|-<br />
| t-showplayers_aura1 || t-showplayers_aura2 || t-playersedit_name || t-playersedit_bar1<br />
|-<br />
| t-playersedit_bar2 || t-playersedit_bar3 || t-playersedit_aura1 || t-playersedit_aura2<br />
|-<br />
| t-lastmove || t-adv_fow_view_distance || t-has_bright_light_vision || t-has_night_vision<br />
|-<br />
| t-night_vision_distance || t-emits_bright_light || t-bright_light_distance || t-emits_low_light<br />
|-<br />
| t-low_light_distance || t-has_limit_field_of_vision || t-limit_field_of_vision_center || t-limit_field_of_vision_total<br />
|-<br />
| t-has_limit_field_of_night_vision || t-limit_field_of_night_vision_center || t-limit_field_of_night_vision_total || t-has_directional_bright_light<br />
|-<br />
| t-directional_bright_light_center || t-directional_bright_light_total || t-has_directional_dim_light || t-directional_dim_light_center<br />
|-<br />
| t-directional_dim_light_total || t-lightColor || || |<br />
|}<br />
<br />
'''''It is important to note that some attributes names on tokens have corresponding attribute names on characters, which represent different values. For example, [*T:id] returns the character ID, while [*T:t-id] returns the token ID.'''''<br />
<br />
=== Subroutine Parameters ===<br />
<br />
When using a gosub statement (-->) or a conditional marked as a gosub (prefixing the label with a > character), you can pass any number of parameters separated by semicolons (;) that the code in the subroutine can utilize.<br />
<br />
Subroutine parameters are numbered starting at 1, and are accessed by using the notation [%number%], so the first parameter is [%1%], the second is [%2%], etc.<br />
<br />
Parameter substitution happens on all line types, and happens prior to character attribute references or roll variable substitution.<br />
<br />
=== Campaign Attribute ===<br />
You can retrieve properties of the API's Campaign object with the [*C:attributename] syntax. For example, [*C:playerpageid] will retrieve the current player ribbon page from the Campaign object.<br />
<br />
=== Page Attributes ===<br />
If you have set the '''activepage''' parameter, you can retrieve page-related properties with the [*P:attributename] syntax, including the page's UDL parameters.<br />
<br />
=== Repeating Section Values ===<br />
<br />
You can reference repeating attribute data using the syntax [*R:attributename] syntax (similar to referencing standard character attributes). The currently active repeating row information will be used to retrieve attribute values. You can also retrieve the full attribute name for a repeating row attribute by using the [*R>attributename] notation. This is useful to pass to things like chatsetattr.<br />
<br />
See the section named [[#Repeating Section Access (--R)|Repeating Section Access]] for more information.<br />
<br />
=== Array Elements ===<br />
After an array has been declared, the elements can be referenced with [@arrayName(index)]. Array indices start at 0.<br />
<br />
== Deferred Resolution for Meta Scripts ==<br />
<br />
As of 1.2.9, ScriptCards supports a deferral character for use when calling another API script with via the <code>--@</code> statement, to defer processing of meta script references so they get processed prior to the sub-API call instead of prior to ScriptCards execution. To defer this processing for meta script ([[Tim#SelectManager|SelectManager]], [[Tim#Fetch|Fetch]]) by inserting a deferral character into the meta call. For example, if I want to have ScriptCards call [[TokenMod]] as if the token for "Quej Gr'stra" (yes, I let Roll20 name my test NPCs) I could use something like this:<br />
<br />
<pre> --@token-mod|{^& select Quej Gr'stra} _on showname</pre><br />
<br />
The <code>^</code> in between <code>{</code> and <code>&</code> will prevent SelectManager from seeing the call when the ScriptCard script is processed, but the <code>--@</code> statement will remove the deferral character so the command that will be sent by ScriptCards is:<br />
<br />
<pre>!token-mod {& select Quej Gr'stra} --on showname</pre><br />
<br />
With the deferral character removed, SelectManager will see the <code>{& select ...}</code> and do its magic.<br />
<br />
While the default deferral character is <code>^</code>, the deferral character is a setting that can be changed:<br />
<br />
<pre> --#deferralcharacter|%</pre><br />
<br />
Will make <code>%</code> the deferral character for future <code>--@</code> statements in the running script.<br />
<br />
Supported [[API:Meta_Scripts|Meta Script]] structures:<br />
* <code>{^&...}</code> - for [[Tim#SelectManager|SelectManager]]<br />
* <code>@^(...)</code> and <code>*^(...)</code> for [[Tim#Fetch|Fetch]]<br />
* <code>get^.</code> and <code>set^.</code> for [[Tim#Fetch|Muler]] (''''' v 1.4.5+ ''''')<br />
<br />
== Arrays ==<br />
<br />
Arrays are a new data type introduced in version 1.1.12 of ScriptCards, and are manipulated with associated function (--~) commands.<br />
<br />
* Arrays are a lists of strings. Items in an array cannot contain the semi-colon (;) character, as that is used to separate parameters in the function code that deals with arrays.<br />
* Arrays are accessed via the --~ script command. In some cases, the value of the tag (variable name) for array commands is not used, and can be a dummy value or simply omitted. I have omitted them in the statements below.<br />
* All commands that DO return a value return string values, even if the content is numeric.<br />
* If a command returns a value and there is some sort of reason that it isn't an array value, you will get "ArrayError" in the return value. This can happen if you reach the end of an array while stepping through it, for example, so checking for "ArrayError" can serve as the end condition for a loop.<br />
* Each array keeps track of its current index, allowing you to step forward and backwards through arrays.<br />
* Any number of arrays can be defined.<br />
* Unlike string variables and roll variables, array variables cannot (currently) be referenced directly. It is necessary to use the function (--~) syntax to manipulate arrays and get values from them as strings for use in other parts of your script.<br />
<br />
== Reentrant Scripts ==<br />
<br />
Reentrant scripts allow you to create buttons in your script code that will re-execute the script at a given label within the code. If you set the reentrant setting (<code>--#reentrant|somevalue</code>) to a non-zero value, your setting and variable information will be preserved between executions. Reentrant script can be used to present menus or choices and then continue acting.<br />
<br />
'''''Important''''': The value of the reentrant setting will be used to identify the appropriate script to resume when reentrancy is used. If more than one character can potentially run the same script at the same time, it is a good practice to include the character ID in the reentrant setting in order to maintain a separate list of variables. Something like:<br />
<br />
<pre><br />
--#reentrant|My Cool Script @{selected|character_id}<br />
</pre><br />
<br />
Reentrant buttons are created with the <code>[rbutton]Caption::ReentryLabel;Parameter[/rbutton]</code> construct. The caption will be displayed on the generated button. <code>ReentryLabel</code> is the name of a label in your script that the button will jump to when clicked, and Parameter will be passed in as a string value called <code>reentryval</code>.<br />
<br />
Example:<br />
<pre><br />
!script {{<br />
--#reentrant|testing<br />
--=Roll|1d20<br />
--+Roll|[$Roll]<br />
--&String|That was a [$Roll.Raw]!<br />
--~x|array;define;MyArray;Apple;Banana;Orange<br />
--+Try it|[rbutton]Hello!::EXEC_PC_SPELL;9[/rbutton]<br />
--X|<br />
<br />
--:EXEC_PC_SPELL|<br />
--+ReentryVal|[&reentryval]<br />
--+The value of Roll is|[$Roll]<br />
--+Value of String|[&String]<br />
--+Array|[@MyArray(0)]<br />
--X|<br />
}}<br />
</pre><br />
<br />
This script sets up some variables and then displays a button labeled "Hello!". If the user clicks the button, the script will be re-entered starting at <code>EXEC_PC_SPELL</code>, which will display the content of the variables from the original execution.<br />
<br />
'''''Note: This section needs to be expanded upon'''''<br />
<br />
==Libraries ==<br />
=== Procedure Libraries ===<br />
<br />
You can now create [[handouts]] in your game in Roll 20 with the name format "ScriptCards Library NAME", where name is a name you assign to the library. Library names are case sensitive. It is my hope that the more proficient ScriptCards scripters out there will provide procedure libraries (or procedures that can be included in libraries) for others to use to make their scripting life easier. Be they specific to a game system, or to a type of activity, I think a robust set of libraries that GMs could use to enhance their scripting capabilities would be very valuable to the community. Should such things begin to emerge, I’ll create a portion of the ScriptCards Wiki page to house them.<br />
<br />
To include one or more libraries in a script, use the +++libname+++ directive (does not need a -- line associated with it). Multiple library names can be specified by separating them with semicolons (i.e., +++General;dnd5elib;Colorize+++ would include three libraries (General, dnd5elib, and Colorize).<br />
<br />
Included libraries are separated from the main script code by the automatic inclusion of "--X|" before the first library is appended to the script, and all libraries are loaded at the end of the script before script processing takes place.<br />
<br />
Procedures and labels in libraries can be used just as if they were included in the body of your script. Note that this DOES mean that you could, technically, jump into a library with a direct branch (--^) or direct branch conditional, but I recommend using libraries to store reusable procedures.<br />
The Notes section of the library handout stores the library code, and is written just like any other ScriptCards code except:<br />
<br />
* They cannot use roll queries (?{Some Prompt:}) to get information from the user at execution time.<br />
* They cannot use @{} notation to access character and token information.<br />
<br />
Both of these limitation stem from the fact that Procedure Libraries are not processed by the chat server, which is what handles these items.<br />
<br />
Here is an example of handling damage modifications (resistance, vulnerability, and immunity) in D&D 5E with a library:<br />
<br />
<pre><br />
!script {{<br />
+++dnd5elib+++<br />
--#|Damage Modifiers Test<br />
--#targettoken|@{target|token_id}<br />
-->Lib5E_CheckDamageModifiers|ResistType;fire<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] fire damage<br />
<br />
-->Lib5E_CheckDamageModifiers|ResistType;cold<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] cold damage<br />
<br />
-->Lib5E_CheckDamageModifiers|ResistType;poison<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] poison damage<br />
<br />
-->Lib5E_CheckDamageModifiers|ResistType;acid<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] acid damage<br />
<br />
--X|<br />
}}<br />
</pre><br />
<br />
Library content (In a handout called “ScriptCards Library dnd5elib” NOTE: Paste into Notepad first and then paste into the handout in Roll20 to avoid bringing over HTML formatting from the web site):<br />
<br />
<pre><br />
--/|ScriptCards Library: dnd5elib version 0.0.1<br />
--/|Provides various utility procedures for D&D 5E games<br />
<br />
--/|Lib5E_CheckDamageModifiers handle damage resistance, vulnerability, and immunity. <br />
--/|Pass a string variable to be filled with a string to be appended to a dice roll and the damage type <br />
<br />
--:Lib5E_CheckDamageModifiers|damageVariableName;damageType<br />
--&[%1%]|<br />
--?"[*T:npc_vulnerabilities]" -inc "[%2%]"|>_Lib5E_IsVulnerable;[%1%]<br />
--?"[*T:npc_resistances]" -inc "[%2%]"|>_Lib5E_IsResistant;[%1%]<br />
--?"[*T:npc_immunities]" -inc "[%2%]"|>_Lib5E_IsImmune;[%1%]<br />
--<|<br />
<br />
--:_Lib5E_IsVulnerable| --&[%1%]| * 2 [Vulnerable] --<|<br />
--:_Lib5E_IsResistant| --&[%1%]| \ 2 [Resistant] --<|<br />
--:_Lib5E_IsImmune| --&[%1%]| * 0 [Immune] --<|<br />
</pre><br />
<br />
The idea is that the functions in the library create a string that can be appended to a roll to modify the output based on resistances, so you pass Lib5E_CheckDamageModifiers the name of the string variable you want to use and the damage type. The variable (ResistType in this case) will include either nothing, “* 2 [Vulnerable]”, “\ 2 [Resistant]”, or “* 0 [Immune]” which can be included in a roll assignment (--=) to modify the damage as appropriate. The order here might be important if an NPC is misconfigured to be both resistant and immune to the same damage type. Since immune is an absolute, having it last ensures that it will override resistant or vulnerable. A creature that is both vulnerable and resistant (again, misconfigured) will come back as resistant since that condition is checked after vulnerable.<br />
Some notes: I prefix my library labels with either “Lib5E_” or “_Lib5E_” as a clarity convention. This isn’t strictly necessary but you should be aware that if two libraries (or if your script and a library) define the same label, the last label defined will win. Since libraries are appended to the end of the script in the order you include them in the +++libname+++ directive, you can somewhat control this, but it is probably best to avoid re-declaring labels. <br />
<br />
In my case, items beginning with “Lib5E_” are intended to be called by scripts, while items beginning with “_Lib5E_” are intended to be used as subroutines by the “public” procedures. Of course, there is no reason you couldn’t call them directly.<br />
<br />
You might also note that I’ve included some library information in comment lines (--/|) at the top of the library. These are ignored by ScriptCards, and are a good way to convey requirements, parameters, usage information, etc.<br />
<br />
=== Example Libraries ===<br />
<br />
==== dnd5elib ====<br />
<br />
[https://github.com/kjaegers/ScriptCards Download the dnd5elib Library from the ScriptCards GitHub]<br />
<br />
The '''dnd5elib''' library provides a collection of utility procedures that help simplify dealing with the D&D 5E Official Sheet. Some of the procedures in this library require '''chatsetattr''' to be installed in your game. This is a growing library, and currently only has a handful of routines. They are:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Procedure Name !! Notes<br />
|-<br />
| style="white-space:nowrap" | Lib5E_CheckDamageModifiers || This procedure can be used to evaluate vulnerabilities, resistances, and invulnerabilities on an NPC. After setting the --#target| parameters, pass the Lib5E_CheckDamageModifiers procedure a variable name (no reference information) and a damage type (i.e., fire, cold, bludgeoning, etc.), and the procedure will then create a string variable with with a name equal to the first parameter that you passed into the procedure. This variable will contain a string that can be included in a roll line (--=), in order to modify the roll as appropriate. For example, '''-->Lib5E_CheckDamageModifiers|ResistType;fire''' will check the current target character's attributes for "fire" and will either return an empty string (no references), "* 0 [Immune]" if the creature is immune, "\ 2 [Resistant]" if the creature is resistant, or "* 2 [Vulnerable]" if the creature is vulnerable to fire damage.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_DeductSpellSlot || Pass in a character_id and a slot level, and the script will expend one spell slot of that level, capping the value at 0 slots remaining. For Example '''<nowiki>-->Lib5E_DeductSpellSlot|@{selected|character_id};1</nowiki>''' to deduct a first level spell slot from the selected character.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_FindResource || Used to locate a resource value on a character. Pass in a character_id, a resource name, and two variable names. The procedure will check both repeating and non-repeating resources looking for a resource whose name matches what was passed in and return three variables. The first will be a string variable named for the 3rd parameter and contains the attribute name of the resource's "name" field. The second will be a string variable named after parameter 4 and contains the resource's value field attribute name, and the third variable is a Roll Variable, also named after the 4th parameter that contains the current resource value. Example: '''<nowiki>-->Lib5E_FindResource|@{selected|character_id};Crossbow bolts;ResName;ResValue</nowiki>''' will find "Crossbow bolts" as a resource on the character and return [&ResName] which is the name of the resource attribute, [&ResValue] which is the '''name of the attribute that stores the value''' and [$ResValue] which is the current numeric value of the resource.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Global_Attack_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Attack Modifiers (repeating_tohitmod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Bless" for 1d4 active and "Being Cool" for +2 active, I will get a return string " + 1d4 [Bless] + 2 [Being Cool]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Save_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Save Modifiers (repeating_savemod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Bless" for 1d4 active and "Being Cool" for +2 active, I will get a return string " + 1d4 [Bless] + 2 [Being Cool]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Skill_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Skill Modifiers (repeating_skillmod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Guidance" for 1d4 active and "Being Cool" for +2 active, I will get a return string " + 1d4 [Guidance] + 2 [Being Cool]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_AC_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Save Modifiers (repeating_savemod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Shield of Faith" with a value of 2 active, I will get a return string " + 2 [Shield of Faith]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Damage_Modifiers || Pass a character ID and TWO string variable to set the return value. The first string will be for normal damage, and the second will be the additional damage on a crit. This procedure will look through the Global Damage Modifiers (repeating_damagemod_*) for rows that are active (checked on the character sheet) and return two strings with the dice rolls and descriptions for them (for example, if I have "Sneak Attack" with a value of 1d6 normal and 1d6 critical damage active, I will get a return string " + 1d6 [Sneak Attack]" and another string of " + 1d6 [Sneak Attack CRIT]" that can be used in a dice rolls.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_DivineSmiteDice || Used to calculate the number of dice to be rolled for a paladin's Divine Smite. Pass a target token id, a spell slot level, and a string variable to be set to the dice roll amount based on the NPC_TYPE attribute of the target token. The returned variable will contain a dice roll (like "3d8" that can be used in a --= line)<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Character_Summary || Pass a character ID to outputs a mini character sheet, including clickable buttons for attacks, actions, legendary actions, etc. Will automatically detect a PC vs NPC and output the appropriate sections.<br />
|}<br />
<br />
Due to formatting issues with the Wiki, the library code has been moved to a [https://gist.github.com/kjaegers/52f6049ddd257f0a1288aca4bbde13c5 GITHUB GIT]. Please view the GIST in raw mode and copy the text and paste it into a handout called "ScriptCards Library dnd5elib" in your Roll20 Game.<br />
<br />
== What to Know if you are Coming from PowerCards ==<br />
<br />
''Note: This section is a work in progress.''<br />
<br />
While ScriptCards and PowerCard have very similar output goals, their internals and use are quite different. The table below summarizes some of the major differences between the scripts.<br />
<br />
::{| class="wikitable"<br />
|-<br />
! PowerCards !! ScriptCards <br />
|-<br />
| With a handful of exceptions, all lines in a PowerCard macro are intended to produce a line of output on the final card. || With ScriptCards, ONLY the <code>--+</code> and <code>--*</code> statement types produces output <br />
|-<br />
| PowerCards lines begin with two dashes (<code>--</code>) followed by a unique tag name for the line, followed by a vertical bar and the content for the line. || ScriptCards lines begin with two dashes (<code>--</code>) followed by a '''statement type identifier''', which is a single character that identifies the type of line to the interpreter. This is followed by a tag (frequently optional), a vertical bar, and the parameters for the statement being executed.<br />
|-<br />
| PowerCard macros are always processed top to bottom. Lines can be hidden so they don't output anything, but there is no looping or branching (<code>--SkipTo</code> looks like a branch, but it just hides all of the lines until the referenced label. || ScriptCards scripts support true branching, including direct branching (<code>--^</code>) and procedure branching (<code>--></code>) and (<code>--<</code>). Procedures support parameters and a call stack so procedures can be nested to call other procedures.<br />
|-<br />
| All lines in a PowerCards macro need to have unique tags because PowerCards builds the card as a single JavaScript object using the tag names to store what will be displayed. This is why repeated tag names always result in the last one being shown. || ScriptCards tags do not need to be unique, and in the case of many line types are optional.<br />
|-<br />
| PowerCards conditionals result in either showing or hiding the line they are on. || ScriptCards conditionals '''''only''''' support branching as the result of the comparison. This branching can be direct (a GOTO) or procedural (a GOSUB) '''''NOTE: As of version 1.2.0, ScriptCards also supports roll/string variable assignment as a result of conditional evaluation, and later versions introduced code blocks that can be implemented as a result of a conditional'''''<br />
|-<br />
| PowerCards relies on the Roll20 [[Quantum Roll]] server and [[Inline|inline rolls]] for all dice functions || ScriptCards includes its own dice roll parser, and '''''does not support''''' [[Inline|inline rolls]]. '''''Note: As of version 1.2.3, ScriptCards will parse [[Inline|inline rolls]], inserting their final value in the place of the roll in the macro, but they are not part of or parsed by the built-in roll parser'''''<br />
|-<br />
| PowerCards RollIDs (often mistaken for variables) are assigned by analyzing the results of an inline roll, and cannot be referenced in other rolls, so you can't roll a <code>1d4</code> and then roll a <code>1d20</code> and add the <code>1d4</code> result because all of the rolls happen on the chat server before PowerCards gets the macro text. || ScriptCards supports two types of variables: <code>Roll Variables</code> and <code>String Variables</code>. Because ScriptCards uses its own roll parser and is not dependent upon the chat server, rolls and their results can be used in other rolls, math functions, output, etc.<br />
|}<br />
<br />
== Example Scripts ==<br />
<br />
'''''Note: The features available in ScriptCards have changed drastically since these examples were written. While these should still work, there are in many cases better ways to do things using language features introduces after these were constructed. Please see the [https://github.com/kjaegers/ScriptCards/tree/main/ScriptExamples Script Examples] section of the official ScriptCards GitHub repository for more updated script examples.<br />
<br />
Below are some sample scripts that utilize the various statement types in ScriptCards:<br />
<br />
=== Divine Smite ===<br />
<br />
This script will prompt the user for a spell slot level to expend on a divine smite. It will check the target's npc_type to see if it is an Undead or Fiend, which adds an additional d8 to the smite roll.<br />
<br />
[[File:ScriptCards Divine Smite.png|Divine Smite Script Output]]<br />
<br />
<pre><br />
!scriptcard {{<br />
--#title|Divine Smite<br />
--=DiceCount|?{Spell Slot Level?|1|2|3|4|5|6|7|8|9} + 1<br />
--=IsFiendOrUndead|0<br />
--?"@{target|npc_type}" -inc fiend|>IsBoosted<br />
--?"@{target|npc_type}" -inc undead|>IsBoosted<br />
--=TotalDice|[$DiceCount] + [$IsFiendOrUndead]<br />
--=SmiteRoll|[$TotalDice]d8<br />
--#emoteText|@{selected|token_name} smites @{target|token_name}<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
--+Smite|deals [$SmiteRoll] radiant damage.<br />
--X|<br />
<br />
--:IsBoosted|<br />
--=IsFiendOrUndead|1<br />
--<|<br />
}}<br />
</pre><br />
<br />
==== How It Works ====<br />
<br />
The first line sets the "title" card parameter to "Divine Smite".<br />
<br />
Line 2 Shows a query to the user asking for the spell slot level, adds one and stores the value in the "DiceCount" Roll Variable. The query/dropdown is generated by the chat server prior to the script being executed.<br />
<br />
Line 3 defaults the "IsFiendOrUndead" Roll Variable to 0.<br />
<br />
Lines 4 and 5 compare the target's "npc_type" attribute (passed by the chat server as text) to see if they include either "undead" or "fiend". If true, the IsBoosted subroutine will be called. No parameters are passed to this subroutine.<br />
<br />
Line 6 sets the "TotalDice" variable to the base (DiceCount) number plus the IsFiendOrUndead number, which will be a 0 or a 1.<br />
<br />
Line 7 calculates "SmiteRoll" by rolling a number of d8 equal to the "TotalDice" value.<br />
<br />
Lines 8-10 set the parameters for the emote, which appears above the card content. By setting the sourceToken and the targetToken, their icons will appear in the emote surrounding the text describing the action.<br />
<br />
Line 11 is the only line that actually produces output on the card. It results in "Smite deals # radiant damage".<br />
<br />
Line 12 ends the script execution, preventing the script from continuing and running the subroutines out of context.<br />
<br />
Lines 14-16 are the IsBoosted subroutine, starting with the :IsBoosted label. The IsFiendOrUndead variable is set to 1, and a return from subroutine is executed.<br />
<br />
=== Magic Missile ===<br />
<br />
This script demonstrates using a loop and calling a subroutine to fire a number of missiles determine by the spell slot level used to cast the spell.<br />
<br />
[[File:ScriptCards_MagicMissile_Fixed.png|Magic Missile Script Output]]<br />
<br />
<pre><br />
!scriptcard {{ <br />
--#title|Magic Missile<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
--=MissileCount|?{Spell Slot Level?|1|2|3|4|5|6|7|8|9} + 2<br />
--=DisplayCount|1<br />
--=MissileDamage|0<br />
--#leftsub|Slot level ?{Spell Slot Level?}<br />
--#rightsub|Ranged Attack<br />
--#emoteText|Fred uses a level ?{Spell Slot Level?} spell slot to fire [$MissileCount.Total] missiles of magical force!<br />
--:MissileLoop|<br />
-->FireMissile|<br />
--=DisplayCount|[$DisplayCount] + 1<br />
--?[$DisplayCount] -le [$MissileCount]|MissileLoop<br />
--+Total|Total damage is [$MissileDamage]<br />
--X|<br />
<br />
--:FireMissile|<br />
--=ThisMissile|1d4 + 1<br />
--=MissileDamage|[$MissileDamage] + [$ThisMissile]<br />
--+Missile|[$DisplayCount.Total] Hits for [$ThisMissile] [b]force[/b] damage<br />
--<|<br />
}}<br />
</pre><br />
<br />
==== How It Works ====<br />
<br />
Lines 1-3 set the card title, the source token and the target token. Setting these tokens causes their icons/avatars to appear in the Emote section of the card.<br />
<br />
Line 4 asks the user what spell slot level they wish to use to cast magic missile. The number of missiles fired is equal to 2 plus the spell level, and this is stored in the MissileCount variable.<br />
<br />
Line 5 stores a 1 in the DisplayCount variable. This will be used to control the loop to determine the number of missiles fired and the missile number when displaying damage rolls.<br />
<br />
Line 6 initializes MissileDamage to 0<br />
<br />
Line 7 sets the left subtitle to the text "Slot Level #", where # is the spell slot level being used.<br />
<br />
Line 8 sets the right subtitle to the text "Ranged Attack".<br />
<br />
Line 9 sets the emoteText parameter with a description of the action, including the slot level and number of missiles fired.<br />
<br />
Line 10 is a label for the missile firing loop<br />
<br />
Line 11 Calls the "FireMissile" subroutine<br />
<br />
Line 12 increases the DisplayCount variable by 1<br />
<br />
Line 13 Checks to see if there are still missles to fire (DisplayCount <= MissileCount) and if so branches to MissileLoop<br />
<br />
Line 14 Displays the total damage dealt by the spell.<br />
<br />
Line 15 stops execution of the script to prevent out of context execution of the subroutine.<br />
<br />
Lines 76-21 are the FireMissile subroutine, beginning with the FireMissile label. The 1d4+1 is rolled and assigned to "ThisMissile". The result is added to the existing MissileDamage total, and a line for the current missile is displayed with the missile number and the damage for the missile.<br />
<br />
=== Longsword Attack ===<br />
<br />
This script demonstrates a standard 5E D&D melee weapon attack, including detection of misses, fumbles, hits, and critical hits. If installed, alterbars is used to decrement the target's BAR3 value by the damage dealt.<br />
<br />
[[File:ScriptCards Longsword.png|Longsword Script Output]]<br />
<br />
<pre><br />
!scriptcard {{<br />
--#title|Longsword<br />
--#leftsub|Melee Attack<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
--#emoteText|@{selected|token_name} attacks @{target|token_name}<br />
--=TargetAC|@{target|npc_ac}<br />
--?[$TargetAC.Total] -gt 0|DoneWithAC<br />
--=TargetAC|@{target|ac}<br />
--:DoneWithAC|<br />
--=AttackRoll|1d20 + @{selected|strength_mod} [STR] + @{selected|pb} [PROF]<br />
--+Attack|@{selected|token_name} rolls [$AttackRoll] vs AC [$TargetAC].<br />
--?[$AttackRoll.Base] -eq 20|Crit<br />
--?[$AttackRoll.Base] -eq 1|Fumble<br />
--?[$AttackRoll.Total] -ge [$TargetAC.Total]|Hit<br />
--+Miss|The attack missed.<br />
--^Final|<br />
<br />
--:Fumble|<br />
--+Fumble!|The attack went horribly wrong.<br />
--^Final|<br />
<br />
--:Hit|<br />
--=Damage|1d8 + @{selected|strength_mod} [STR]<br />
--+Hit!|The attack hit @{target|token_name} for [$Damage] slashing damage.<br />
--@alter|_target|@{target|token_id} _bar|3 _amount|-[$Damage]<br />
--^Final|<br />
<br />
--:Crit|<br />
--=Damage|1d8 + @{selected|strength_mod} [STR] + 1d8 [CRIT]<br />
--+Critical Hit!|The attack hit @{target|token_name} for [$Damage] slashing damage.<br />
--@alter|_target|@{target|token_id} _bar|3 _amount|-[$Damage]<br />
<br />
--:Final|<br />
}}<br />
</pre><br />
<br />
==== How it Works ====<br />
<br />
In lines 1-5, we set the title, subtitle, and emote text along with the tokens for the emote area.<br />
<br />
Lines 6-9 allow us to determine the AC of the target. On the 5E Roll20 sheet, NPCs armor class is stored in "npc_ac", while PCs armor class is in "ac". First we grab npc_ac and if it is zero, we check AC.<br />
<br />
Line 10 rolls the attack roll, rolling 1d20 and adding the attacker's strength modifier and proficiency bonus<br />
<br />
Line 11 displays the result of the attack roll on the card<br />
<br />
Lines 12-14 determine what kind of result the attack had. If the .Base value of the roll was 20, we branch to "Crit". If it was 1, we branch to "Fumble". If the .Total value of the roll was greater than or equal to the AC that was determined in Lines 6-9, we branch to Hit.<br />
<br />
Assuming we didn't branc anywhere, the result of the attack was a miss, so we display that on line 15 and then branch to "Final"<br />
<br />
This is followed by three branch segments, :Fumble, :Hit, and :Crit. A fumble displays a text message and branches to :Final.<br />
<br />
On a hit or a crit, we roll Damage (adding additional damage dice on a crit). We display a "Hit!" or "Critical Hit!" message and then make an API call to AlterBars, passing it the token id, bar we want to modify (3 in this case), and the amount we want to modify by the Damage value.<br />
<br />
=== Party Health Status ===<br />
<br />
This example calculates the current Hit Points remaining and HP percentage for each character and creates a color-coded display with the current party status.<br />
<br />
[[File:ScriptCards Party Health.png]]<br />
<br />
<pre><br />
!scriptcard {{<br />
--#title|Party Status<br />
--#titleCardBackground|#33CC33<br />
--#oddrowbackground|#bfee90<br />
--#evenrowbackground|#90eebf<br />
-->HealthCheck|@{Quej Grastra|character_id}<br />
-->HealthCheck|@{Brim Cheuto|character_id}<br />
-->HealthCheck|@{Odug Ututees|character_id}<br />
--X|End of card Execution<br />
<br />
--:HealthCheck|<br />
--=HealthPerc|[*[%1%]:hp] / [*[%1%]:hp^] * 100 \ 1<br />
--=HealthColor|000000<br />
--?[$HealthPerc.Total] -gt 50|HealthSkip<br />
--=HealthColor|FF0000<br />
--:HealthSkip|<br />
--+[*[%1%]:character_name]|has [#[$HealthColor.RollText]][*[%1%]:hp] of [*[%1%]:hp^][/#] HP [R]([$HealthPerc.Total]%)[/R]<br />
--<|End of HealthCheck<br />
}}<br />
</pre><br />
<br />
==== How it Works ====<br />
<br />
Lines 1-4, we set the card title, and set the title background and row background colors to shades of green.<br />
<br />
Lines 5-7 make gosub calls the the "HealthCheck" subroutine, passing in the character ID of each of the named characters (these are the names of the characters in my test game)<br />
<br />
Line 8 terminates the script execution.<br />
<br />
The remaining lines of the script are the HealthCheck subroutine, which works like this:<br />
<br />
Line 10 is the subroutine label (:HealthCheck)<br />
<br />
Line 11 uses the character id passed as a parameter and combines it with character attribute lookup *(...) to retrieve the value of "hp" and "hp<nowiki>^</nowiki>" for the character. The <nowiki>^</nowiki> character is used to specify that we want the MAX value for this attribute for the second call. We divide these two numbers and multiple by 100 to get a percentage. Finally, we use integer division by 1 to round the percentage and drop the decimals. The end result gets stored in the HealthPerc roll variable.<br />
<br />
Line 12 defaults to color of the health text to black<br />
<br />
Line 13 check to see if the health percentage is greater than 50. If so, it branches to HealthSkip, preventing the script from executing line 13.<br />
<br />
Line 14 sets the color of the health text to red<br />
<br />
Line 15 is the label that will be branched to from Line 13 to skip the red coloring<br />
<br />
Line 16 again uses character attribute substitution and the passed parameter value to output a display line containing the character name, the colorized health total, and the percentage value. The percentage is right-justified.<br />
<br />
Line 17 returns from the HealthCheck subroutine.<br />
<br />
=== Expanded Magic Missile Script ===<br />
<br />
This is the expanded and enhanced version of the Magic Missile script covered in {{yt|watch?v=u50xvNzS9Zk | this video}}. It includes visual and audio effects, checking and deducting spell slots, and applying damage using either Token-Mod or Alterbars.<br />
<br />
<pre><br />
!scriptcard {{ <br />
--#title|Magic Missile<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
<br />
-->GetAndCheckSlotInformation|<br />
<br />
--=MissileCount|[$SlotLevel] + 2<br />
--=DisplayCount|1<br />
--=MissileDamage|0<br />
--#leftsub|Slot level [$SlotLevel]<br />
--#rightsub|Ranged Attack<br />
--#emoteText|@{selected|character_name} uses a level [$SlotLevel.Total] spell slot to fire [$MissileCount.Total] missiles of magical force!<br />
<br />
--:MissileLoop|<br />
-->FireMissile|<br />
--=DisplayCount|[$DisplayCount] + 1<br />
--?[$DisplayCount] -le [$MissileCount]|MissileLoop<br />
--+Total|Total damage is [$MissileDamage]<br />
-->DeductSpellSlot|<br />
--#rightsub|Level [$SlotLevel] Left: [$SlotsRemaining] <br />
-->PlayEffects|none;burst-smoke;beam-magic;spell_01<br />
-->ApplyDamageTokenmod|@{target|token_id};3;-[$MissileDamage]<br />
-->ApplyDamageAlterbars|@{target|token_id};3;-[$MissileDamage]<br />
--X|<br />
<br />
--:FireMissile|<br />
--=ThisMissile|1d4 + 1<br />
--=MissileDamage|[$MissileDamage] + [$ThisMissile]<br />
--+Missile|[$DisplayCount.Total] Hits for [$ThisMissile] [b]force[/b] damage<br />
--<|<br />
<br />
--:GetAndCheckSlotInformation|<br />
--=SlotLevel|?{Spell Slot Level?|1|2|3|4|5|6|7|8|9}<br />
--=SlotsTotal|[*S:lvl[$SlotLevel]_slots_total]<br />
--=SlotsExpended|[*S:lvl[$SlotLevel]_slots_expended]<br />
--?[$SlotsExpended.Total] -ge [$SlotsTotal.Total]|NoSlotsLeft<br />
--<|<br />
<br />
--:NoSlotsLeft|<br />
--+|[*S:character_name] has no level [$SlotLevel.Total] spell slots available.<br />
--X|<br />
<br />
--:DeductSpellSlot|<br />
--=SlotsExpended|[$SlotsExpended] + 1<br />
--@setattr|_charid [*S:character_id] _lvl[$SlotLevel]_slots_expended|[$SlotsExpended] _silent<br />
--=SlotsRemaining|[$SlotsTotal] - [$SlotsExpended]<br />
--<|<br />
<br />
--:PlayEffects|Parameters are : source effect; target effect; line effect; sound effect<br />
--vtoken|@{selected|token_id} [%1%]<br />
--vtoken|@{target|token_id} [%2%]<br />
--vbetweentokens|@{selected|token_id} @{target|token_id} [%3%]<br />
--@roll20AM|_audio,play,nomenu|[%4%]<br />
--<|<br />
<br />
--:ApplyDamageTokenmod|Parameters are tokenid;bar#;amount<br />
--@token-mod|_ignore-selected _ids [%1%] _set bar[%2%]_value|[%3%]<br />
--<|<br />
<br />
--:ApplyDamageAlterbars|<br />
--@alter|_target|[%1%] _bar|[%2%] _amount|[%3%]<br />
--<|<br />
}}<br />
</pre><br />
<br />
===Hidden Roll===<br />
<br />
A roll where only the GM sees the result of the roll.<br />
[[File:Scriptcards-hiddenroll.png|right]]<br />
<pre><br />
!script {{<br />
--#title|Stealth Check<br />
--=Roll|1d20 + @{selected|stealth}<br />
--+|@{selected|token_name} attempts to move undetected...<br />
--*GMLine|@{selected|token_name} rolled a [$Roll]<br />
}}<br />
</pre><br />
<br />
===Elsewhere===<br />
* {{fpl|10000297/ Scritpcard API Working and Sharing}}<br />
* [https://gist.github.com/dubzilla1/cba439bd1f47ecdd81d0c79a482c4a91 Pathfinder 2E heal macros]<br />
<br />
[[Category:Featured articles]]</div>5004103https://wiki.roll20.net/User:104025User:1040252021-10-15T17:11:55Z<p>5004103: /* API Scripts */</p>
<hr />
<div>{{revdate}}'''{{user profile|104025|The Aaron}}''' is an active and longstanding Roll20 community member, Forum Champion, and prolific [[:Category:API Author|API Author]].<br />
<br clear=right><br />
{{userboxtop | toptext = }}<br />
{{Userbox Central Time}}<br />
{{Userbox Mentor}}<br />
{{Userboxbreak}}<br />
{{userbox All Opinions}}<br />
{{userbox Arcane Scriptomancer}}<br />
{{userbox LFG}}<br />
{{userbox Never Ending Story}}<br />
{{userbox Patron}}<br />
{{userbox Tutorial}}<br />
{{userbox Profile complete}}<br />
{{userbox Rollin}}<br />
{{userbox Script Runner}}<br />
{{Userboxbreak}}<br />
{{userbox Bug Hunter|10}}<br />
{{userbox Consecutive Days|10}}<br />
{{userbox Played|1000}}<br />
{{userbox Played With|250}}<br />
{{userbox GM Count|10}}<br />
{{userbox Rolled|10000}}<br />
{{userboxbottom}}<br />
==The Aaron, Arcane Scriptomancer==<br />
<br />
''"While wizards may learn to bend magic to their will, the Scriptomancer alone understands the language of the gods, in which the very building blocks of the world are written. Wielding both his esoteric knowledge and the hammer of the Ay'p Eye, The Aaron reshapes the world at its most fundamental level, producing results that benefit the common man; though their workings may be beyond mortal comprehension."'' - Quote from {{forum|permalink/1423307/ PaulOoshun}} <br />
<br />
<br />
===Support my work on [https://www.patreon.com/shdwjk Patreon] or [https://www.paypal.me/shdwjk Paypal.me]===<br />
<br />
If you use my scripts, want to contribute, '''and have the spare bucks to do so''', go right ahead. However, please don't feel like you must contribute just to use them! I'd much rather have happy Roll20 users armed with my scripts than people not using them out of some sense of shame. Use them and be happy, completely guilt-free!<br />
<br />
'''Disclaimer:''' ''These Patreon campaigns and Paypal.me links are not affiliated with Roll20; as such, contributions are voluntary and Roll20 cannot provide support or refunds for contributions.''<br />
<br />
==Links==<br />
* {{user profile|104025|The Aaron}} - Roll20 Profile<br />
* [https://www.patreon.com/shdwjk Patreon] - Support his work with Roll20 APIs<br />
* [http://roll20api.net/ Roll20API.net] - Companion site for the [[Script:Walls|Walls]] & {{forum|permalink/8824428/ UniversalVTTImport}} APIs.<br />
* {{repo|shdwjk/Roll20API shdwjk/Roll20API}} - all his APIs, some which aren't in the one-click install<br />
* {{repo|shdwjk/TheAaronSheet TheAaronSheet}} - A facade for [[Sheetworker]] Tasks and Utility Functions<br />
<br />
(Thanks for always assisting and creating cool scripts. [[User:1048758|AquaAlex]])<br />
<br />
== API Scripts ==<br />
The Aaron have created a massive amount of API scripts, of which 56 are in the API one-click menu, and other smaller, one-off scripts written on the fly for smaller things, can be found scattered through the Roll20 Forums.<br />
<br />
Popular APIs/Highlights:<br />
* '''Tokens'''<br />
** [[TokenMod]]<br />
** {{fpl|10226949/ Bump}} -- provides a way to invisibly manipulate tokens on the GM Layer from the Objects Layer, and vice versa<br />
** [[Script:Token Name Number|TokenNameNumber]] -- Automatic numbering of tokens with special placeholder.<br />
** {{fpl|7992951/ TokenCondition}} -- Easily add full Token Condition Images to Character and Monster Tokens.<br />
* '''Combat/Characters'''<br />
** [[GroupInitiative]]<br />
** [[Script:Ammo|Ammo]] update characters ammo count<br />
** {{fpl|10212772/ AddCustomTurn}} -- An easy way to add (and remove) custom turns which increment or decrement, and have auto delete features.<br />
** {{fpl|9888024/ PlayerCharacters}} -- List all Player Characters divided by Player for the GM, or all assigned Characters for a Player. Add Characters for GM and Players<br />
* '''Map/Dynamic Lighting'''<br />
** [[Script:Walls|Walls]] – Builds dynamic lighting walls based on imported <code>.svg</code> file<br />
** {{fpl|9521203/ UDLWindows}} – create/convert Dynamic Lighting walls that are see-through, but blocks movement.<br />
** {{fpl|9939691/ UDLPasswall}} – Walls that block sight, but not movement!<br />
** {{fpl|8824428/ UniversalVTTImporter}} -- Import .dd2vtt files to create Dynamic Lighting Lines and Lights!<br />
** {{fpl|2948292/ DryErase}} – An API that can stop players from [[Drawing Tool|drawing]] on the map, deleting any drawing instantly.<br />
* [[API:Short Community Scripts]]<br />
<br />
<br />
===Misc API threads===<br />
* [https://app.roll20.net/forum/post/907343/script-mystara-calendar#post-909985 Calendar (Mystara)] -- Currently just supports the Mystara Calendar (12 months, 12 days, etc), but I play to expand it to be a more universal campaign calendar, including annotation of dates, personal notes, tracking the passage of time, etc.<br />
* <strike>[https://app.roll20.net/forum/post/920764/script-isgm-id-function-auto-populated#post-925675 isGM] -- Provides a function isGM() for determining if a player id refers to a gm. Unlike other solutions, this one builds it GM list automatically by detection via chat messages. The first time a player speaks as themselves, they are detected as being either a GM or a Player, and that determination is stored in the state object. This is native functionality with the <code>playerIsGM()</code> function now.<br />
* <strike>[https://app.roll20.net/forum/post/931415/script-turnmarker-turn-token-highlight-round-counter-player-advance-command-turn-announce-plus-spiny-graphics-if-you-want-them#post-934023 TurnMarker] -- A feature rich turn marker with round announce, turn change announce, auto sizing graphics, etc. </strike> really Old API. There are many newer & better APIs that can do the same & better<br />
<br /><br />
[[Category:API Author]]<br />
[[Category:Forum Champion]]</div>5004103https://wiki.roll20.net/D%26D_5E_by_Roll20D&D 5E by Roll202021-10-12T17:45:04Z<p>5004103: /* PC */</p>
<hr />
<div>{{revdate}}{{HCbox|{{hc|360037773573-5th-Edition-OGL-by-Roll20 D&D 5E by Roll20}} }}<br />
[[File:5E OGL Sheet Core v2.6.png|500px|thumb|right|The '''D&D 5E by Roll20''' Character Sheet]]<br />
<br />
This is the community-driven documentation for the '''[[5E|D&D 5E]] by Roll20''' character sheet. Previously the sheet was known as the '''"5th Edition OGL Sheet"''' or just the '''"OGL Sheet"'''.<br />
<br />
=The Basics=<br />
This page is a ''[[Community Wiki]]'' guide to the Official D&D 5th Edition character sheet, which is updated with info tricks that might not be covered by the {{hc|articles/360037773573-5th-Edition-OGL-by-Roll20 official sheet documentation}}.<br />
<br />
<br />
To find out about the latest updates, issues and talk about the sheet, check the {{fpl|10096810/ D&D 5th Edition by Roll20 (Q2Y2021)}}-thread on the {{forum|category/277980 forums}}.<br />
<br />
<br />
[[Bug|Bug reports]] for the sheet is best reported in the same thread. If you find bugs in the 5E Compendium or 5E marketplace content, {{bug}}.<br />
<br />
<br />
__TOC__<br />
<br />
==Adding the Character Sheet to a Game==<br />
[[File:D&D5E-Roll20-sheet-selection.png|300px|thumb|right|The Sheet Selection Menu]]An official or community contributed character sheet [[Add_character_sheet#Adding_a_Character_Sheet_to_your_Campaign|can be added to any game when you first create it]]. On the Game Creation screen, underneath the large blue '''“I’m Ready, Create Game!”''' button, is the '''“Optional: Choose a Character Sheet”''' section. Located here is a drop down menu that lists all the character sheets built either by Roll20 officially or created by the community. These sheets are sorted under their respective RPG Systems in alphanumerical order. Once selected, a preview of the character sheet will load upon the creation page for you to review as well as showcase relevant information about the sheet, such as the sheet’s creator and its key features.<br />
<br />
<br />
The '''D&D 5E by Roll20''' Sheet can be found under either: '''Sheets by Roll20''' → D&D 5E by Roll20 OR '''Dungeons and Dragons 5E''' → D&D 5E by Roll20<br />
<br />
<br />
If you want to add a character sheet to an existing campaign, you can find this drop down menu once again by accessing the [[Game Settings Page]] from the [[Game_Management#Game_Details_Page|Game Details]]-page.<br />
<br />
{{mbox | text = '''NOTE:''' If you have added custom attributes to your character journals prior to adding a character sheet to a campaign, you may want to delete them first. Adding a character sheet to a campaign will create its own set of custom attributes on all of your character journals, but it will reuse any attributes encountered if they share the same name. This can cause calculation issues on the sheet.}}<br />
<br />
<br />
If you were previously using either the [[DnD5e Shaped Character Sheet|D&D 5E (Shaped)]] or [[DnD5E_Community_Contributed|D&D 5E (Community Contributed)]] sheets and wish to transfer over to the '''D&D 5E by Roll20''' version, it's a good idea to ask help on the [https://app.roll20.net/forum/category/277980 forums].<br />
<br />
<div style="clear: both"></div><br />
<br />
==Where to Find the Sheet==<br />
Once a character sheet has been added to a game, and once inside it, on all [[Journal#Characters|Characters Journals]], a new tab will be available between the '''“Bio & Info”''' and '''“Attributes & Abilities”''' tab labelled '''“Character Sheet”'''. Much like the Attributes & Abilities tab, only players who have been granted Edit permissions for the journal entry will be able to access the Character Sheet tab.<br />
<br />
''See also:'' '''[[Add_character_sheet#Adding_New_Characters_In-Game|Create new character sheets to your players]]'''<br />
<br />
==Sheet Features==<br />
The '''D&D 5E by Roll20''' sheet has all of the functionality of a pen and paper character sheet, and much more. Certain aspects of the sheet have been streamlined or automated to remove bookkeeping and speed up gameplay. The key features are auto-calculations, [[Macro|macro]] buttons, and [[D&D 5e by Roll20 Roll Templates|roll templates]]. The sheet defaults to using the rules as printed in the D&D 5E SRD, however it's dynamic enough to allow you and your group to use many custom house rules you might want.<br />
<br />
===Auto Calculations===<br />
Many parts of the sheet use auto calculations to fill in derived attributes with the expectation that you're using the rules as printed in the 5th Edition SRD. Many of these calculated traits can be modified from the character sheet's <span style="font-family:Pictos;">y</span> [[D&D 5E by Roll20#Settings Page|Settings]]-tab, and those set by Sheet Workers can be edited directly. Below are some examples of Sheet Worker and Auto Calculation functionality:<br />
<br />
* '''Class''' - Changing the character's class from the header will automatically update the character's saving throw proficiencies, their hit die type, spell casting ability, and spell save DC. <br />
* '''Level''' - Changing the character's level will also update their proficiency bonus, number of spells per day, and more.<br />
* '''Attributes''' - Changing one of the character's attributes will also update the related modifier, skills that are based on that attribute, and derived stats such as initiative or passive perception.<br />
<br />
===Roll Buttons and Roll Templates===<br />
[[File:5E_OGL_Sheet_Rollable_Buttons.gif|right|frame|Any label that highlights in red when the mouse hovers over it is rollable.]]<br />
''Main Page:'' '''[[D&D 5e by Roll20 Roll Templates|D&D 5E by Roll20 Roll templates]]'''<br />
<br />
Most of the stats in the game can be rolled by hovering over their name, the stat will turn red, and then left-clicking the mouse. This is true for Attributes, Saves, Skills, Hit Dice, Death Saves, Tool Proficiencies, Attacks & Spellcasting, Spell Cards, and NPC Actions/Attacks. Any of these roll buttons can be dragged directly from the sheet to your [[Macro Quick Bar]], enabled from the <span style="font-family:Pictos;">y</span> [[My Settings]]-tab of Roll20's [[Sidebar]].<br />
<br />
Player characters have both a simple and attack [[D&D 5e by Roll20 Roll Templates|roll template]] that is output to the {{Text Chat}}-tab on the right hand [[Sidebar]]. The simple template is used for everything except for attacks. The attack template is shaped to show up in three pieces; the attack at the top, information in the middle, and damage at the bottom. Depending on your sheet settings, the damage will not roll automatically unless you click on the name of the attack from the roll template in the chat tab. This was designed to simulate the tabletop experience of rolling to attack and then rolling damage if necessary. You can change this behavior in the sheet <span style="font-family:Pictos;">y</span> [[D&D 5E by Roll20#Settings Page|Settings]]-tab, tab under "Auto Damage Roll".<br />
<br />
<div style="clear: both"></div><br />
<br />
====Rolling for Advantage and Disadvantage====<br />
With the '''D&D 5E by Roll20''' Sheet, the [[D&D 5E by Roll20#Settings Page|default sheet settings]] has Advantage set to ''always'' rolled for convenience purposes. It is commonly agreed upon that a gaming group uses the left roll result when advantage is not being used for a check. When advantage or disadvantage is in play, simply choose the higher or lower result among the two per usual. You can change this behavior in the sheet <span style="font-family:Pictos;">y</span> [[D&D 5E by Roll20#Settings Page|Settings]]-tab (gear icon at the top right of the page), tab under "Roll Queries". You have the choice of "Always Roll Advantage" (the default setting), "Advantage Toggle", "Query Advantage", or "Never Roll Advantage".<br />
<br />
'''Advantage Toggle:''' The Advantage Toggle will add three buttons to the top of your character sheet: "Advantage", "Normal", and "Disadvantage". You can click on any of these to roll for Advantage (the highest roll result will highlight in black), Disadvantage (the lowest roll result will highlight in black), or a single d20.<br />
<br />
'''Query Advantage:''' The Query Advantage setting will prompt a dialog box to appear whenever you roll from your sheet. It will ask you to select what sort of roll want to do (Normal, Advantage, Disadvantage). After choosing the type you want, the roll will occur in chat.<br />
<br />
'''Never Roll Advantage:''' When rolling from your sheet, only a single d20 will be rolled.<br />
<br />
===Resizable Text Fields===<br />
[[File:5E_OGL_Sheet_Resizable_Text_Fields.gif|right|frame|Making a text field larger is just a matter of click and dragging.]]There are many free-text fields on the sheet that give you a place to keep information that doesn't necessarily follow a specific format. All of the fields on the Bio Tab are free-text fields as well as the Description fields present for attacks, spells, equipment, features & traits, and NPC actions. If your text overflows past the bottom of a text field, you can resize it to view the content in its entirety by clicking and dragging the bottom right corner icon shown in the adjoining image.<br />
<br />
<br />
At present, these fields can only contain raw text. There are no formatting options (bold, italic, etc.) available.<br />
<br />
<div style="clear: both"></div><br />
<br />
===The Padlock Button and Organizing Elements===<br />
(aka. '''[[Character_Sheets#Repeating_Section|Repeating Section]]''')<br />
[[File:5E_OGL_Sheet_Padlock.gif|right|frame|The Padlock Toggle]]There is a <span style="font-family:Pictos;">(</span> (padlock) icon set at the bottom of several different fields of the '''D&D 5E by Roll20''' Sheet. It is used where a player is meant to add entries such as individual attacks, actions, pieces of equipment, features & traits, tool proficiences & custom skills, other proficiencies & languages, and spells. This icon behaves as a toggle button. <br />
<br />
When set in the <span style="font-family:Pictos;">(</span> locked position (default), a player can add new entries into the field. When the button is toggled to <span style="font-family:Pictos;">)</span>(unlocked), a player can no longer add new entries, but they will be able to reorder or delete any of the existing ones. The <span style="font-family:Pictos;">#</span>(red trash bin)-icon overlaid on the right hand side of the entry will delete it.<br />
<br />
{{Ambox<br />
|nocat=true<br />
| type = content<br />
| text = '''Deleting an entry cannot be undone!''' On left side of every entry while the padlock is <span style="font-family:Pictos;">)</span> unlocked is a re-sort icon symbolized by '''<big>≡</big>'''(three parallel lines). By clicking and dragging on this icon, you can rearrange the order of the entries in the field.<br />
}}<br />
<br />
{{Ambox<br />
|nocat=true<br />
| type = content<br />
| text = Some of the features of '''Repeating Sections''' do not work when the [[Character_Sheets#Character_Sheet_in_a_separate_window|Character Sheet is in a separate window]].<br />
}}<br />
<br />
<br />
<div style="clear: both"></div><br />
<br />
==Utilizing the 5th Edition SRD Compendium==<br />
[[File:5E_OGL_Sheet_Compendium.png|right|The Compendium Tab]]Upon adding the D&D 5E by Roll20 Character Sheet to a campaign, the [https://app.roll20.net/compendium/dnd5e/BookIndex| 5th Edition SRD Compendium] is automatically enabled for use from it's own <span style="font-family:Pictos;">i</span> [[Compendium]]-tab in the '''[[Sidebar]]''' of the application. It's located between the {{Journal}} and <span style="font-family:Pictos Custom;">u</span> [[Jukebox]]-tabs, and is accessible for both GM and Player alike.<br />
<br />
<br />
The <span style="font-family:Pictos;">i</span> [[Compendium]] allows for rapid searching of all rules, classes, monsters, spells, items, and more that are included in the 5th Edition SRD. This minimizes time spent for the gaming group to leaf through a book in the middle of a session for a rule clarification. Even better, both the GM and the Player can utilize dragging and dropping* from the <span style="font-family:Pictos;">i</span> [[Compendium]]-tab directly to your character sheets. This makes statting NPCs and PCs far faster than inputing everything manually.<br />
<br />
{{mbox | text = '''NOTE:''' The 5th Edition SRD is similar but NOT identical to the ''Dungeons and Dragons'' 5th Edition Rule Book. Some skills, classes, creatures, items, and other elements found within the ''Dungeons and Dragons'' rule book are strictly intellectual property of Wizards of the Coast and not accessible through their Open-Game License(OGL).}}<br />
<br />
<br />
===Statting PCs===<br />
Dragging from the <span style="font-family:Pictos;">i</span> [[Compendium]] works for the Equipment and Spell fields of the PC Sheet. This will not only carry over the name of the item or spell, but the relevant attack and damage rolls and any rules or flavor text that comes with it. Adding Compendium items in this fashion also automatically adds the equipment item (if it's a weapon) or spell to the Attacks & Spellcasting field to roll directly from. Items that modify a character's Attributes, Saves, AC, To Hit, Damage, Spell Attacks, and Spell DC will be automatically calculated on the sheet when dragged in. For example, if a Belt of Giant Strength is dragged to a sheet, the strength Attribute Score will become highlighted in blue and its attribute score will be increased. An asterisk is appended to the right of the score to also signify that it has been modified by an item. When you mouse over this number, the strength Attribute Score will revert back to what its unmodified total so you can refer back to it. Dropping a Compendium items that is an ammunition type (arrows, crossbow bolts, blowgun darts, etc) will automatically fill out a resource field for that item and link it to its entry in the Equipment section.<br />
<br />
To insert a Compendium item into the character sheet, run a search for the Item or Spell you want to add in the <span style="font-family:Pictos;">i</span> [[Compendium]]-tab. Once found, click and drag on the Compendium item's name so that it creates a little named tile that follows along with your mouse. Drag this over to the character sheet, it doesn't matter where. A text box that reads, "ACCEPTING DROP FROM COMPENDIUM" will appear on your sheet if this is done correctly. Let go of the tile and the entry will be auto-completed with all the data pertaining to the the Compendium entry in the correct location on the sheet. You can see this in action below under [[#Equipment|Equipment]].<br />
<br />
===Statting NPCs===<br />
You can fill out an entire NPC sheet in a single drag and drop. Run a search for the NPC you want to create from the <span style="font-family:Pictos;">i</span> [[Compendium]]-tab. Once found, click and drag on the NPC name so that it creates a little named tile that follows along with your mouse. Drag this to anywhere over the Tabletop area of the screen. Let go of the tile and a new character journal will be created named after the NPC from the Compendium entry. Its sheet will be changed over to the NPC sheet and filled with the entire NPC entry from the Compendium including their Actions, Reactions, and Legendary Actions if applicable. If you're using one of the Compendium expansions bought from the Roll20 Marketplace like the Monster Manual or Volo's Guide to Monsters, token art will also be pulled from the Compendium entry, placed on the table, and linked to your NPC's journal.<br />
<br />
You can also drag an NPC entry from the Compendium to an existing journal entry if you have the sheet open. If the sheet is in PC sheet mode, it will automatically change it over to the NPC sheet, and add its entry elements to it.<br />
<br />
One thing to note about dragging a stat block over from the Compendium is that it uses an ''additive'' behavior. It will not replace anything that you have already entered manually.<br />
<br />
=The PC Sheet=<br />
The '''D&D 5E by Roll20 Sheet''' contains both the PC Sheet ''and'' the NPC Sheet. By default, a new character journal is set to the PC sheet, but you can switch between the two by toggling it from the [[#Settings Page|General Options Settings]]. The PC Sheet is split up into four pages and can be selected from the buttons just underneath the header at the top of the sheet. They are listed from left to right order: The [[#Core Page|Core Page]], The [[#Bio Page|Bio Page]], The [[#Spells Page|Spells Page]], and The [[#Setting Page|Setting Page]].<br />
<br />
== Creating and Leveling up a character with Charactermancer ==<br />
Players and GMs using the '''D&D 5E by Roll20''' Sheet can use the Charactermancer to create and level up characters.<br />
<br />
'''How to use the Charactermancer for [[Charactermancer (D&D Fifth Edition)|character creation and leveling]].'''<br />
<br />
<br />
{{Ambox<br />
|nocat=true<br />
| type = content<br />
| text = The Charactermancer do not work when the [[Character_Sheets#Character_Sheet_in_a_separate_window|Character Sheet is in a separate window]].<br />
}}<br />
<br />
==Core Page==<br />
[[File:5E_OGL_PC_Core_Guide.jpg|right|frame|The Core Page]]The Core Page is selected by default and has most of the information you'll want to use on a regular basis to play your character. This should look very similar to the content you would normally find on the first sheet of the physical "D&D 5E by Roll20" player character sheet. The screenshot at the top of this wiki page displays the entirety of the Core Page. <br />
===(1) Core Header===<br />
[[File:D&D5E-Roll20-core-header.png|550px]]<br />
<br />
The header block at the top of the sheet changes based on the page you have selected. On the Core page you can select a class by its dropdown menu. The available options from the dropdown are: Barbarian, Bard, Cleric, Druid, Fighter, Monk, Paladin, Ranger, Rogue, Sorcerer, Warlock, and Wizard. You can create a custom class from the Settings Page.<br />
<br />
Once a class has been selected you can update the class's level by changing the number next to the class. The sheet will also automatically mark the abilities that class has proficiency in as well as automatically select the dice that will be used when Hit Dice are rolled. You can change the Hit Dice setting manually from the options menu. If your character multi-classes, then the secondary class and its level will appear beside the primary class. This Class and Level field can hold up to four classes if desired.<br />
<br />
The fields for Background, Race, Alignment, and Experience Points allow you to fill in whatever text you wish to put in them. The Character Name persists over all pages of the sheet and is tied to the name you give to the journal entry. Changing it on the sheet itself will also change the name on the character journal and vice versa once it is closed.<br />
<br />
===(2) Attributes===<br />
<br />
[[File:5E_OGL_Sheet_Attribute_Block.jpg|left]]Along the left side of the sheet are listed the 6 primary attributes: Strength, Dexterity, Constitution, Intelligence, Wisdom, and Charisma. These attributes are used by almost every other calculation on the sheet, as they are the core definition of a character. Each attribute block has the core attribute score, which can be changed by modifying the number in the oval at the bottom of each block, and, inside the square, the attribute modifier which is auto-calculated based on the score below it. All racial ability score increases must be manually added to the core attribute score using the settings "gear" symbol at the top of the page (where the Core, Bio, and Spells buttons are located.) The attribute modifier uses the following calculation to set the value:<br />
<br />
<br />
<code>[[floor((@{strength}-10)/2)]]</code><br />
<br />
The attribute can be referenced by its name, such as @{dexterity} while the attributes modifier can be referenced by adding the mod suffix, @{dexterity_mod}.<br />
<br />
<div style="clear: both"></div><br />
<br />
===(3) Inspiration===<br />
<br />
[[File:D&D5E-Roll20-inspiration.png|left]]You can track whether or not you have Inspiration by clicking the circle next to the Inspiration block at the top left of the Core page. This will toggle a dragon spiral icon on and off for indication purposes.<br />
<br />
<div style="clear: both"></div><br />
<br />
===(4) Proficiency Bonus===<br />
<br />
[[File:5E_OGL_Sheet_Proficiency.png|left]]Your character's proficiency bonus is listed near the top left of the page. You cannot modify this value manually, instead it is automatically set based off your character's over-all level. Your character's Level can be set by changing the number next to your Class name in the [[#header_info|Header]] at the top when on the Core page.<br />
<br />
<div style="clear: both"></div><br />
<br />
===(5) Saving Throws===<br />
<br />
[[File:5E_OGL_Sheet_Saving_Throws.png|left]]Next to the core Attributes on the left side of the page is a list of the same attributes to be used in making saving throws. To mark an attribute that your character has proficiency in for saving throws, check the box next to the appropriate attributes. When you select a class in the header section of the Core page it will automatically check the correct boxes for that class's proficiencies.<br />
<br />
You can add an additional field to Saving Throws to serve as a Global Save Modifier. An example is if the character is under the influence of the Bless spell and can roll a 1d4 in addition to the result of their saving throws. This is enabled from the Settings Page under General Options. Once enabled a seventh checkbox and field will be added at the bottom of the Saving Throws block with a text field to enter the additional die roll. For this example, you could enter "1d4[BLESS]" in the global checkbox's text field that you can enable when the character is under the effects of the Bless spell. The word between the brackets becomes a label that can be seen when you mouse over the roll result in chat. While this Global Save Modifier is checked, every roll made from the Saving Throws block and performing a Death Save will add this modifier to the result.<br />
<br />
<div style="clear: both"></div><br />
<br />
===(6) Skills===<br />
[[File:5E_OGL_Sheet_Skills.png|left]]<br />
To the right of the Core Attributes is a list of all of the character's Skills. Each skill can be rolled by clicking on the skill name. If you have proficiency in a specific skill, then you would check the box next to the skill name, this will automatically add your proficiency bonus to that skill's checks. Each skill also lists the core attribute, that is used in the roll calculations, next to it in parenthesis.<br />
<br />
You can set advanced skill options for the Settings page, such as skill expertise, flat bonuses from class archetypes or feats, as well as Jack of All Trades.<br />
<br />
<div style="clear: both"></div><br />
<br />
===(7) Armor Class, Initiative, & Speed===<br />
<br />
[[File:D&D5E-Roll20-AC-Init-Speed.png|left]]The Armor Class & Speed blocks at the top center of the page can be used to keep track of your Armor and Speed values. The Initiative block cannot be modified manually, but instead is auto-calculated based off your character's Dexterity. If you have any additional initiative modifiers you can add them on the {{gear}} [[#Settings Page|Settings Page]] under Initiative Modifier in the Class Options block.<br />
<br />
Armor Class can also be tracked automatically by using the [https://app.roll20.net/compendium/dnd5e/BookIndex Compendium] compatible inventory, on by default.<br />
<br />
You can configure a custom AC calculation using the {{gear}} [[#Settings Page|Settings Page]] under the Attribute Tracking section. It's listed as "Armor Class Tracking" and is set to "Automatic" by default. If you select Custom, you can select up to two different attributes to apply to the character's armor class.<br />
<div style="clear: both"></div><br />
<br />
====Using the Global AC Modifiers====<br />
If you check the "Show Global AC Modifier" field in the character sheet General Options settings, the sheet will display a repeating section to configure and apply different modifiers to AC. So, for example, if your character has a common bonus, such as from a spell or a conditional feat or fighting style, you can toggle that AC bonus from the character sheet directly.<br />
<br />
====Rolling for Initiative and the Turn Order Tracker====<br />
Clicking on the word INITIATIVE will roll that character's initiative score. If your players have [[Token|tokens]] linked to their character sheets, they can roll their initiative ''and'' simultaneously add their character and its initiative score to the {{Turn Tracker}} automatically. What is required of the player is that their linked token must be currently selected on the Tabletop before they roll off their sheet.<br />
<br />
If you would like to enable a tie breaker component to Initiative, there is an option to enable this from the [[#Settings Page|Settings Page]] under the "Attribute Options" block. What this does is that it will add your dexterity Attribute Score as a decimal value to your Initiative. So if you have a character with a dexterity attribute score of 14, your initiative modifier will change from a <code>2</code> to a <code>2.14</code>.<br />
<br />
===(8) Hit Points & Temporary Hit Points===<br />
[[File:5E_OGL_Sheet_HP.png|left]]The Current Hit Points and Temporary Hit Points blocks are used to keep track of your character's Hit Points (HP). Inside the Current Hit Points block, at the top, is a line that lists the character's maximum amount of HP. <br />
<br />
<br />
When your character takes damage, if they have any, it should be subtracted from their Temporary Hit Points first, then any remaining damage would then come off of the character's Current Hit Points.<br />
<br />
<div style="clear: both"></div><br />
<br />
===(9) Hit Dice===<br />
[[File:5E_OGL_Sheet_Hit_Dice2.png|left]] The Hit Dice block is used to keep track of and roll your character's hit dice. Inside the Hit Dice block, at the top, is a line to keep track of the total number of dice your character can have. In the main area of the block you would keep track of the remaining hit dice. Clicking the "HIT DICE" label will roll the hit dice for your selected class automatically. If you wish to change the dice that is rolled you can do so in the Class Options section of the [[#Settings Page|Settings Page]] ({{gear}} icon). <br />
<br />
<br />
If your character is multi-classed, when rolling your hit dice (by clicking "''HIT DICE''", a pop-up will ask which of your character's current class's hit dice you want to roll. This input accepts only numerals a input to make automatic tracking of the [[API:A Guide to the API|API]] possible.<br />
<div style="clear: both"></div><br />
<br />
===(10) Death Saves===<br />
[[File:5E_OGL_Sheet_Death_Saves.png|left]]The Death Saves block is used to keep track of your character's death save rolls once they have been knocked out. You can click the "DEATH SAVES" label to make a death save roll. If you roll greater than 10 you would check one of the boxes next to "Successes" otherwise you would check a box next to "Failures". If your character has any modifiers to their death save rolls they can be added in the Class Options section of the Settings Page(gear icon).<br />
<div style="clear: both"></div><br />
<br />
===(11) Attacks & Spellcasting===<br />
[[File:5E_OGL_Sheet_Attacks_And_Spellcasting.png|left]]The Attacks & Spellcasting block in the center of the Core page of this character sheet will be one of the most often used sections. To start, you can manually add any attack or spell to this section by hovering over the block and clicking the "Add" button(the <span style="font-family:Pictos;">&</span> symbol). This will open a form that can be filled out with all of the information about the specific attack or spell you are adding. <br />
<br />
<br />
This section will automatically add attacks, with all the stats, for spells that have an attack component when they are added to your spell sheet on the [[#Spells Page|Spells Page]]. This happen both if you add the spell manually or if you drag and drop a spell from the <span style="font-family:Pictos;">i</span> [[Compendium]]. An attack is also automatically created if you drag and drop an item from the Compendium into your sheet.<br />
<br />
<div style="clear: both"></div><br />
[[File:Poisoned Dagger 5e Attack.png|right|frame|An example of an attack form filled out for a physical attack using a +1 Poisoned Dagger]]For example, lets say Erin the Bold has a +1 Poisoned Dagger that has the stats of a regular dagger, but also metes out an additional 1d6 of poison damage alongside the typical 1d4 points of piercing damage. The image displayed to the right is how the attack would be set up:<br />
<br />
<br />
Since this is a [https://app.roll20.net/compendium/dnd5e/Items:Dagger#h-Dagger dagger], and daggers have the "[https://app.roll20.net/compendium/dnd5e/Weapons#h-Weapons Finesse]" attribute I can chose either STR or DEX for my bonus attribute. Erin is quicker than she is strong, so we will pick DEX as the attribute to attack with, as well as checking the "proficient" checkbox since Erin is experienced with using these sorts of weapons. She doesn't have any other gear that might make her attacks better, so we will leave the generic bonus between the attribute and proficiency blank, or 0. Being a +1 Poisoned Dagger means that it is also magical, so it gets a 1 in the magic bonus slot just below. A dagger can also be used as a thrown weapon, so we've added the weapon's throwing range info to the "Range" field. Since a weapon does damage, we have checked the first "Damage" checkbox and filled in the required fields. This dagger does 1d4 piercing damage + Erin's DEX mod + 0 bonus damage (this would be used for bonus damage on top of the magical +1) and it doesn't have anything to change the critical damage so we just put the same damage into the "crit" box. Because this dagger can also cause poison damage, we also check the second "Damage" checkbox and fill in the info for the 2nd set of damage. The poison does a flat 1d6 poison with no extra bonuses, so we've selected "-" to say there is no attribute that adds to this damage. This damage also doesn't have anything to make the crit different so we set that to 1d6 as well. There are no extra saving throws or effects that are included with this attack, so we leave these additional sections blank. <br />
<br />
These additional effect sections will be used more commonly with spells, like [https://app.roll20.net/compendium/dnd5e/Fireball#h-Fireball Fireball], where you would require a DEX save against your SPELL DC, which will be set according to your character's spell casting level. For a fireball, the save effect would be "half damage" and the "Description" would be something like "Hits all creatures within 20 ft of the explosion point".<br />
<br />
After you are done modifying all of individual stats for an attack you can click the gear icon at the top right of that section and it will hide the stats for that attack. If ever you need to change these stats in the future you can hover over the entry and click the <span style="font-family:Pictos;">y</span>(gear)-icon that shows up to unhide the stats section. <br />
<br />
<div style="clear: both"></div><br />
====Adding Global Attack and Damage Modifier====<br />
You can add two special entries to the Attacks & Spellcasting block to handle to global Attacks and Damage modifications to rolls. An example is if the character is under the influence of the Bless spell and can roll a 1d4 in addition to the result of their attack roll. This is enabled from the [[#Settings Page|Settings Page]] under General Options. Once enabled, a checkbox will be added at the bottom of the Attacks & Spellcasting block with a text field to enter the additional die roll. For this example, you could enter <nowiki>"1d4[BLESS]"</nowiki> in the global checkbox's text field that you can enable when the character is under the effects of the Bless spell. The word between the brackets becomes a label that can be seen when you mouse over the roll result in chat. While these Global Modifiers are checked, every roll made from the Attacks & Spellcasting block will add these modifiers to the result.<br />
<br />
====Rolling from the Attacks & Spellcasting Block====<br />
[[File:Poisoned Dagger 5e Roll.png|frame|An attack roll from a +1 Poisoned Dagger]]Rolling from the Attacks & Spellcasting Block is no different than rolling from any other portions of the character sheet. Hovering your mouse over any entry here will highlight its entire label (NAME, ATK, and DAMAGE/TYPE) in red and you'll be able to click on it to roll the attack or spell. You can also drag this entry into the Macro Bar to give yourself easy access to this attack. Because this is a repeating section, the macro name will be a bit messy, but you can right-click the button and rename the macro to whatever you like.<br />
<br />
With any attack that checks for AC, you will see TWO rolls set side by side for the Armor Class check with the name of the attack listed underneath them with the Attack modifier bonus (ATK) appended to the Attack name in light grey. The Roll20 D&D 5E Character Sheet ''always'' rolls for Advantage by default, so you will always have two roll results for this check (most gaming groups use the left roll result if neither Advantage or Disadvantage is being factored in the check). If there is a specified range for the attack, this will be listed above the attack's name.<br />
<br />
Underneath the AC Check and Attack Name is the Damage roll result for the attack. Underneath this roll result will be the Damage Type (ex. slashing, piercing, poison, fire, etc.) listed in light grey italicized font.<br />
<br />
For spells that don't check for AC and instead require a Saving Throws to mitigate or negate the spell's effect, the SPELL DC is listed first. Underneath this, in italicized font, is the effect if a character succeeds the check listed. Underneath the effect is the required attribute saving throw that must be rolled. If Damage is applied, this result is rolled and listed next with its Damage Type.<br />
<br />
[[File:5e_attack_example.gif|right|frame|How to view attack damage when the sheet is set to "Don't Auto Roll Damage"]]<br /><br />
<br />
<br />
{{mbox | text = '''NOTE:''' If your character sheet's Settings have "Auto Damage Roll" set to "Don't Auto Roll Damage" under General Options, the damage will not be listed underneath the AC roll result in chat. The damage was rolled, but presently hidden from view. Anyone can see the damage delivered by manually unfolding the roll result open by hovering your mouse over the roll result in chat and clicking on the attack/spell's name.}}<br />
<div style="clear: both"></div><br />
<br />
===(12) Personality Traits, Ideals, Bonds, and Flaws===<br />
These text fields lock to prevent accidental edits. When a sheet is first created, these fields are unlocked and given a dashed yellow border to the top of the field to showcase that they're editable. To lock the field after entering text, click on the gear icon in the upper right corner of the field. This will remove the yellow border and the field will conform in height to display everything within it.<br />
<br />
There presently isn't a means to format the raw text (italicize, bold, font alignment, etc) within these fields and any line breaks are stripped out. If you ever need to edit the content again while the field is locked, mouse over the desired field and the gear icon will reappear in the top right. Clicking on that will unlock the field once again for edits.<br />
<br />
===(13) Class & Other Resources===<br />
[[File:5E_OGL_Sheet_Resources.png]]<br />
<br />
The Class & Other Resource Blocks can be used to keep track of either an item quantity you have in your equipment (like arrows in a quiver), or skills that don't fit into the other sections on the sheet (like a '''Sorcerer's Sorcery Points''', a '''Cleric's Channel Divinity''' at higher levels, or the number of rounds a '''Barbarian''' has been '''Raging''' so far in a combat encounter).<br />
<br />
There are 3 fields per Block:<br />
* Resource Max:<br />
** The Resource Max field is a text box which allows you to quantify exactly what you're tracking (ex. "Total: 10 Rounds").<br />
* Resource:<br />
** The Resource field is a numeral that you dial up or down or input directly.<br />
* Resource Name:<br />
** The Resource Name is a text box that allows you to label the resource when you click on the light grey "OTHER RESOURCE" label to overwrite it with your own.<br />
**"OTHER RESOURCE" is placeholder text<br />
<br />
<br />
A resource block will be filled automatically if you checkmark an Equipment item as "USE AS A RESOURCE" & the Item Quantity field will be paired with the Resource field in the Resource block & vice versa (you'll need to click outside of the field or hit Enter for changes to refresh across the sheet). If the two resource blocks given by default are not enough then you can add additional blocks by hovering over the section & clicking the "Add" (+ symbol) button.<br />
<br />
The Item Name will also be added to the Resource Name field, however the Resource Max field is apparently not linked to the Item currently.<br />
<br />
If you drag & drop an ammunition item type from the Compendium into your character sheet, the item is added to the Equipment block & is automatically listed & linked as an Other Resource.<br />
<div style="clear: both"></div><br />
To call the first set of class resources use:<br />
* Class Resource <code>@{class_resource}</code><br />
* Other Resource <code>@{other_resource}</code><br />
<br />
<br />
To call the Repeating resources use<br />
* Repeating Resource 1st left<code>@{repeating_resource_$0_resource_left}</code><br />
* Repeating Resource 1st right<code>@{repeating_resource_$0_resource_right}</code><br />
* Repeating Resource 2nd left<code>@{repeating_resource_$1_resource_left}</code><br />
* Repeating Resource 2nd right<code>@{repeating_resource_$1_resource_right}</code><br />
* etc.<br />
<br />
<br />
If you want to do a basic Full Readout of the Repeating Resource, the Format would be (Top Left to Bottom Right):<br />
* Class: <code>@{class_resource_name}: @{class_resource} / @{class_resource|max}</code><br />
* Other: <code>@{other_resource_name}: @{other_resource} / @{other_resource|max}</code><br />
* Left 0: <code>@{repeating_resource_$0_resource_left_name}: @{repeating_resource_$0_resource_left} / @{repeating_resource_$0_resource_left|max}</code><br />
* Right 0: <code>@{repeating_resource_$0_resource_right_name}: @{repeating_resource_$0_resource_right} / @{repeating_resource_$0_resource_right|max}</code><br />
* Left 1: <code>@{repeating_resource_$1_resource_left_name}: @{repeating_resource_$1_resource_left} / @{repeating_resource_$1_resource_left|max}</code><br />
* Right 1: <code>@{repeating_resource_$1_resource_right_name}: @{repeating_resource_$1_resource_right} / @{repeating_resource_$1_resource_right|max}</code><br />
* etc.<br />
<br />
===(14) Tool Proficiencies===<br />
[[File:5E_OGL_Sheet_Tool_Proficiencies.png|left]]The Tool Proficiencies block is for listing a character's Tool Proficiency skills. At the bottom of this block is an "Add" (<span style="font-family:Pictos;">&</span> symbol) button. Clicking this will add a new entry to this block where you can add all of the relative stats for a specific tool proficiency, say Woodcarver's Tools. You can set the level of proficiency to either Proficient, Expertise, or Jack of All Trades. The roll bonus for that tool will reflect the proficiency level selected. Next is an Attribute drop down menu where you can select which character attribute to roll with for a proficiency check. One of the options you can choose is "QUERY ATTRIBUTE" which when you click on the Tool Proficiency to roll it, you will be prompted to choose which attribute you would like to use. The attribute used for the check will be up to the GM when it is time to make the roll check. If there is any additional bonus modifiers that come along with the tool in question, you can input it in the "MODS:" field.<br />
<br />
Once you finished filling out the stats for this tool you can click the <span style="font-family:Pictos;">y</span>(gear) icon at the top right of the entry to hide the stat fields and leaving behind just the rollable button. You can roll by either clicking on this rollable button or dragging it to your [[Macro Bar]].<br />
<br />
You can also use this section to create custom skills or rolls for your campaign setting or home-brew ruleset. Check out the [[#Custom Skills and Stats|Advanced Use]] section for further details.<br />
<br />
====Global Skill Modifier====<br />
You can add a special entry to the Tool Proficiencies & Custom Skills block to handle to global Attacks and Damage modifications to rolls. An example is if the character is under the influence of the Guidance spell and can roll a 1d4 in addition to the result of their skill check. This feature is enabled from the [[#Settings Page|Settings Page]] under General Options. Once enabled, a checkbox will be added at the bottom of the Tool Proficiences & Custom Skills block with a text field to enter the additional die roll.<br />
<br />
For this example, you could enter "1d4[Guidance]" in the global checkbox's text field that you can enable when the character is under the effects of the Guidance spell. The word between the brackets becomes a label that can be seen when you mouse over the roll result in chat. While this Global Modifier is checked, every roll made from the Tool Proficiencies & Custom Skills block and the Skills block will add this modifier to the result.<br />
<div style="clear: both"></div><br />
<br />
===(15) Other Proficiencies & Languages===<br />
[[File:5E OGL Sheet Proficiencies.png|left]]<br />
This block can be set up to be Compendium Compatible (where you can add repeating sections for individual items) or as one resizable free-text field to enter whatever you wish in here. If you don't feel the Tool Proficiency block is needed (as in, you don't feel like your party will ever have to roll individual tool sets), you can store a character's Tool Proficiencies here instead. There presently isn't a means to format the raw text (italicize, bold, font alignment, etc). You can adjust this block's behavior by going to the Settings Page of the sheet and going to the General Options block to change whether this block uses the Simple or Compendium Compatible layout.<br />
<br />
When the Other Proficiences & Languages block is made Compendium Compatible, each repeating field lists a Type selection field and a Proficiency text field. Type has the following options available from its drop down selection menu: Language, Weapon, Armor, Other. <br />
<p style="clear:both;"></p><br />
<br />
===(16) Equipment===<br />
[[File:5E OGL Sheet Equipment.png|framed|right|The Equipment block of the PC Sheet]]<br />
The Equipment block at the bottom of the page has 2 different versions: a Simple version that features a single plain text field where you can track all of your equipment in any format you wish and a Compendium Compatible version that allows you to drag and drop items from the Compendium to automatically populate repeated sections for each indivdual piece of equipment.<br />
<br />
To swap between the two different Equipment block versions, first, go to the sheet's Settings Page (gear icon at the top right of the page) and then to the "General Options" section. Here, on the field labeled "Inventory", you can select between "Simple" or "Compendium Compatible" respectively. Like the name implies, if you want to be able to copy items directly from the Compendium using drag and drop, you must use the Compendium Compatible version. Dragging item entries from the Compendium to the character sheet will add it fully filled in the Equipment section as well as other automated actions described below.<br />
<br />
====Automated Compendium Functionality====<br />
If you populate the Equipment block by dragging and dropping <span style="font-family:Pictos;">i</span> [[Compendium]] items, there are several automatic features that occur when the entries you drag in our equipment items.<br />
Auto-Equip: Every item dragged to the sheet is automatically equipped in the Equipment Section<br />
*'''Weapons:''' A weapon dragged in from the Compendium will add an attack in the Attacks and Spellcasting section for that item.<br />
*'''Armor:''' Armor that is dragged in from the Compendium will add its bonus to the Armor Class (while equipped) section. If you drag multiple pieces of armor to the same sheet and at least two armor entries are equipped at once, a warning will pop up in red at the top of the Equipment Block that the Armor Class isn't being correctly calculated because of the bonus overlap. This warning will dissapear when you unequip down to a single set of armor.<br />
*'''Magical/Wondrous Items:''' Items that modify Attributes, Saves, AC, To Hit, Damage, Spell Attacks, and Spell DC will add that bonus to those elements on the sheet. In most cases, the attribute that is being modified will highlight in blue and followed with an asterisk to showcase that the attribute is being modified by an item. Mousing over the modified number will display the base value of that attribute before the item's modification is applied. This stat modification only applies if the item is equipped in the Equipment section and it will remove its bonus if it is unequipped.<br />
*'''Ammunition:''' Items dragged in from the Compendium that are used for ammunition such as arrows, bolts, darts, and slingstones, will automatically populate and link to an Other Resource field.<br />
<br />
====Manually Adding Items====<br />
You can also add items manually by hovering over the block and clicking the "Add" button (+ symbol). Each equipment entry, by default, show fields for quantity, name, and weight of an item. If you hover over a row and click the small "information" icon (grey-filled circle with a lowercase i centered in it) that appears at the bottom right of the entry you can also set some additional features. <br />
<br />
*'''Equipped Checkbox:''' The checkbox changes the appearance of the Item Name so it's easier to tell what your character currently has equipped from a glance. When left unchecked, the Item Name's font turns grey. When checked, the Item Name becomes a solid black.<br />
*Use As A Resource Checkbox: When checked, this will enable one of the Class Resource blocks and list the item name and its quantity within it. The quantity is tied between the two so changing it in one will be reflected in the other field after clicking outside the field.<br />
*'''PROP:''' This is a text field where you would take note of weapon properties such as ''finesse'', ''versatile'', or ''light''.<br />
*'''MODS:''' This is a text field where you would take note if an item (likely magical) would modify your stats in some fashion such as a character's Attributes, Saves, Skills, AC, To Hit, Damage, Spell Attacks, and Spell DC. If a stat is modified here, its attribute value will become highlighted in blue and adjusted by the supplied modifier listed here. An asterisk is appended to the right of the value to also signify that it has been modified by an item. While your mouse is hovering over the attribute, it will revert back to its unmodified total so you can refer back to its pre-moddified value.<br />
**The format for a stat modification is ''stat name:n'' where n is the stat bonus (ex. ''Strength:21'')<br />
*'''Description Field:''' This is a simple text field to include a description of the particular item and of any special qualities or effects it might have on the player.<br />
Some if not all of these fields will be filled in automatically when adding from the Compendium (where applicable).<br />
<br />
Both versions of the equipment field have the sections for each of the [https://app.roll20.net/compendium/dnd5e/Treasure#h-Treasure coins] you may find on your adventures: copper(CP), silver(SP), electrum(EP), gold(GP), and platinum(PP).<br />
<br />
====Encumbrance====<br />
If you are following Encumbrance rules, the <span style="font-family:Pictos;">i</span> [[Compendium|Compendium Compatible]] Equipment block will automatically calculate and track the weight of your character's backpack if you enter the weight values for any of the items in your Equipment list. When your character becomes encumbered, and depending on its severity, the words ENCUMBERED, HEAVILY ENCUMBERED, or IMMOBILE will display in red underneath the TOTAL WEIGHT value. You can also choose to follow Simple, Variant Encumbrance rules, or not follow Encumbrance rules at all by toggling it off on the [[D&D 5E by Roll20#Settings Page|Settings Page]] under "General Options".<br />
<br />
====Mods====<br />
The Mods field of each piece of equipment can modify the values of ability scores, AC, saving throws, Skill (Ability) checks and more. What follows is a list of the modifiers, and the proper syntax for adding them.<br />
<br />
All modifiers are separated by commas. There are other modifiers that can appear the mod field, used in creating the item from a compendium drag and drop operation, but the modifiers below have live effects on the character sheet, depending on if the item is marked as “equipped”.<br />
<br />
'''replace the <code>+n</code>, with the number you want.''' For example, if you want to boost Animal Handling skill by 3, you look at the table and find <code>Animal Handling +n</code>, so you will add to your item <code>Animal Handling +3</code>.<br />
<br />
{| class="wikitable" <br />
|-<br />
! Modifier<br /><br />
! Effect<br /><br />
|-<br />
| style="width: 20%;" | '''Combat Modifiers'''<br />
| '''These affect items that provide attacks (Appear in the attack section of the character sheet)'''<br />
|-<br />
| Melee Attacks +n<br />
| Adds +n hit "Magic Bonus" to that attack. It is not global, and only affects a weapon(melee or ranged), not an item, staff or other category. The bonus is figured into the attacks display on the 5e sheet.<br />It is NOT ''Melee Attack''.<br />
|-<br />
| Melee Damage +n<br />
| Adds +n damage "Magic Bonus" to that attack. It is not global, and only affects a weapon(melee or ranged), not an item, staff or other category. The bonus is listed separately in the attacks display on the 5e sheet.<br />
|-<br />
| Spell Attack +n<br />
| Adds a global +n to the character's Spell Attack bonus.<br />It is NOT ''Spell Attacks.''<br />
|-<br />
| '''Saving Throws'''<br />
| '''All modifiers stack with “Saving Throws +n'''<br />
|-<br />
| Strength Save +n,<br />Dexterity Save +n,<br />Constitution Save +n,<br />Intelligence Save +n,<br />Wisdom Save +n,<br />Charisma Save +n<br />
| Adds a +n to the indicated saving throw<br />''Do not use a colon.''<br />
|-<br />
| Saving Throws +n<br />
| Adds a Global Modifier to ALL saving throws.<br />
|-<br />
| Spell DC +n<br />
| Adds a global +n to a spell casting character’s Spell Save DC.<br />It is NOT Spell ''Save'' DC.<br />
|-<br />
| '''Ability Scores'''<br />
| <br />
|-<br />
| Strength +n,<br />Dexterity +n,<br />Constitution +n,<br />Intelligence +n,<br />Wisdom +n,<br />Charisma +n<br />
| Provides a bonus to the indicated ability score, which will appear in blue on the sheet while the bonus is active.<br />Do not use a colon. ''Strength: +10'' will do nothing<br />
|-<br />
| Strength n,<br />Dexterity n,<br />Constitution n,<br />Intelligence n,<br />Wisdom n,<br />Charisma n<br />
| Replaces the indicated ability score, which will appear in blue on the sheet while the bonus is active.<br />Do not use a colon. ''Strength: 10'' will do nothing<br />
|-<br />
| '''Skills'''<br />
| <br />
|-<br />
| Acrobatics +n,<br />Animal Handling +n,<br />Arcana +n,<br />Athletics +n,<br />Deception +n,<br />History +n,<br />Insight +n,<br />Intimidation +n,<br />Investigation +n,<br />Medicine +n,<br />Nature +n,<br />Perception +n,<br />Performance +n,<br />Persuasion +n,<br />Religion +n,<br />Sleight of Hand +n,<br />Stealth +n,<br />Survival +n<br />
| Adds the value to the indicated Skill roll. Note that in this case, the <code>+</code> and a colon are optional. <code>Acrobatics +5</code>, <code>Acrobatics 5</code>, <code>Acrobatics: +5</code>, <code>Acrobatics: 5</code> will all add <code>5</code> to the character’s Skill roll. For consistency and to guard against future functionality, it’s probably best to follow the format for ability scores, and use a plus sign with no comma: <code>Acrobatics +5</code>.<br />There is no Global Skill modifier<br />
|-<br />
| '''AC'''<br />
| <br />
|-<br />
| AC +n<br />
| By itself, <code>AC: 13</code> adds 13 to the character’s Armor Class. It does not replace it. <br /><br />If <code>Shield</code>, <code>Light Armor</code>, <code>Medium Armor</code>, or <code>Heavy Armor</code> is also in the mods field, it will change the calculation.<br />''<code>Light Armor, AC: 13</code>'' will give a formula of 13 + dex mod<br />''<code>Medium Armor, AC: 13</code>'' will give a formula of 13 + dex mod (max +2)<br />''<code>Heavy Armor, AC: 13</code>'' will give you flat AC 13<br />''Shield, AC: 13'' would add 13 to the your AC. The Shield keyword is superfluous in this case.<br />''<code>Shield, AC: 2</code>'' will just add 2 to the AC.<br />Finally, a bare modifier, such as for a Ring of Protection can just be written as <code>AC: +2</code> or <code>AC +1</code>.<br /><br />Shield or bare AC bonuses will stack with other armor mods on different items. You cannot equip multiple armors simultaneously, or have a custom armor equation on the settings tab and wear an armor. This will generate a flag.<br /><br />The + and a colon are semi-optional. <code>AC +5</code>, <code>AC: +5</code>, <code>AC: 5</code> will all work. However, <code>AC 5</code> will do nothing. For consistency and to guard against future functionality, it’s probably best to indicate a base AC as <code>AC: n</code> and a Shield as <code>AC +n</code>.<br />At this point, there is no way to differentiate between Ranged AC and Melee AC, though some magic items such as the ''Arrow Catching Shield'' make the distinction.<br />
|}<br />
<br />
<br />
<br />
<div style="clear: both"></div><br />
<br />
===(17) Features & Traits===<br />
[[File:5E OGL Sheet Features Traits.png|thumbnail|left|The Compendium Compatible itemized version of the Features & Traits section]]<br />
The '''Features and Traits '''-block is the place to store '''Class-''', '''Race-''' and '''Background Features''', '''Feats''', and other special notes about your character or of a certain piece of equipment or ability. When using the Charactermancer, the previously mentioned features appears in this section.<br />
<br />
This block can be set up to be <span style="font-family:Pictos;">i</span> [[Compendium|Compendium Compatible]] (where you can add repeating sections for individual items) or as one resizable free-text field to enter whatever you wish in here. You can adjust this block's behavior by going to the [[D&D 5E by Roll20#Settings Page|Settings Page]] of the sheet and going to the '''General Options'''-block to change whether this block uses the Simple or Compendium Compatible layout. <br />
<br />
When adding items to the Compendium Compatible version of this block, you have the <code>Name</code> field, a <code>Source</code>-field where you can choose between (Racial, Class, Feat, Background, or Other) , a <code>Source Type</code>-text field to describe the type, and then the multilined <code>Description</code>-textbox. Clicking on the <span style="font-family:Pictos;">y</span>(gear)-icon in the top right corner of the item will lock/unlock the item's editability. When locked down, a <span style="font-family:Pictos;">w</span>(chat bubble)-icon appears when you mouse over the feature/trait. Clicking on the <span style="font-family:Pictos;">w</span> will share this feature's description in the {{Text Chat}}.<br />
<br />
There presently isn't a means to format the raw text (italicize, bold, font alignment, etc) of the Simple version or in the Description section of either version of the Features & Traits block.<br />
<br />
You can drag-n-drop '''Feats''' from the compendium, even though they can't be selected in the Charactermancer on levelup.<br />
<br />
PC Features and Traits can be called using an ability roll:<br />
<code>%{selected|repeating_traits_$0_output}</code><br />
Simply increase the $0 value to access all Features and Traits listed on the character sheet, $1, $2, $3...<br />
<br />
<p style="clear:both;"></p><br />
<br />
==Bio Page==<br />
[[File:D&D5E-Roll20-BIO-tab.png|right|thumb|250px|The Bio Page of the PC Sheet]]The Bio page, opened by selecting "BIO" from the 4 buttons near the top right of the sheet, is comprised of free-form text fields that can be used to keep track of less "structured" information about your character. You can use this page to describe your character's appearance, keep track of who their allies are and what organizations they've worked for, and on this page is a section to supplement the inventory list, on the front page, with the "Treasure" section, where you can keep track of all the loot you find along your travels.<br />
===Bio Header===<br />
[[File:D&D5E-Roll20-Bio-header.png|550px]]<br /><br />
<br />
The header of the Bio page contains the basic run down of a character's physical appearance.<br />
*'''Character Name:''' This is carried over from every single PC Page and matches the character journal's name<br />
*'''Age:''' The character's current age<br />
*'''Size:''' The size classification for the race type (Medium for most cases)<br />
*'''Height:''' The character's height<br />
*'''Weight:''' The character's weight<br />
*'''Eyes:''' The character's eye color<br />
*'''Skin:''' The character's skin color<br />
*'''Hair:''' The character's hair color/style<br />
<br />
===Character Appearance===<br />
While the Bio Header describes the bare bone physical characteristics of a PC, this field is for fleshing out the visual peculiarities and/or cues of your character. Does you character have a piercing gaze? A stooped posture? Are they fancily dressed or are their clothes moth-eaten? In essence, this field is for everything and anything one would note about the character–from the equipment or garb they wear to how they comport themself.<br />
<br />
===Allies & Organization===<br />
This text field is for listing important or campaign relevant NPCs that the character may have a connection with. It's also for keeping track of faction allegiance. In the case of ''Dungeons & Dragons''' Forgotten Realms world, a PC could be a member of the Harpers or the Emerald Enclave, among other major factions who are all vying for power of the continent.<br />
<br />
===Character Backstory===<br />
This field is for listing your character's pre-campaign history, their relations, and the pertinent places they have been to in the past.<br />
<br />
===Additional Features & Traits===<br />
This text field is a continuation of the [[#.2817.29_Features_.26_Traits | Features & Traits]] section of the Core Page. The section on the Core Page is a good place for commonly utilized features of a character or briefly jotting down an abbreviated list. This field on the Bio page gives you more real estate to fully write down everything you need in whole.<br />
<br />
===Treasure===<br />
This text field is where you can list all the loot you've collected while searching bodies and delving through dungeons. Since much of these effects are transient and are likely to be used, given away, or sold to the highest bidder at the earliest opportunity, this may be preferable place to keep this list of items rather than adding them to the itemized Compendium Compatible Equipment section (if you have that version enabled).<br />
<br />
==Spell Page==<br />
[[File:D&D5E-Roll20-Spells-tab.png|right|thumb|400px|The Spell Page]]The Spell page, opened by selecting the "SPELLS" button from the four buttons near the top right of the sheet, is used to keep track of all of the powerful magics at your character's fingertips.<br />
<br />
===Spell Page Header===<br />
[[File:D&D5E-Roll20-Spells-header.png|550px]]On the Spells page Header you can set the ability modifier that will be used for casting spells. Selecting the Spellcasting Ability block will allow you to select an attribute from a dropdown, and this will be used in all relevant spell rolls. This attribute will be set automatically when you select a spell casting class. The next two blocks, the Save DC and Attack Bonus will be set automatically based on the class that is selected on the Core page.<br />
<br />
===Spellcasting Ability===<br />
The Spellcasting Ability modifier will automatically update, depending on the class you select on the Core page, to the correct ability modifier for your class. If, for some reason, you need to change this value you can click on the modifier listed in this section and it will give you a drop-down list of all available ability modifiers.<br />
<br />
===Spell Save DC & Attack===<br />
The Spell Save DC and Spell Attack Bonus sections cannot be changed manually, but are just a visual output of modifiers that will be happening behind the scenes. The Spell Attack Bonus is the number that will be added to all spell attack rolls, automatically.<br />
<br />
The Spell Save DC refers to the Save DC that enemies will have to beat when they are trying to dodge/resist your incoming spells. Say, Fred the Sorcerer casts Lightning bolt, and his Spell Save DC is 14. Any enemies hit by his attack will have to make a DEX save and try to beat 14. If they manage to beat the attack, then they are only grazed and take half of the damage. If they don't beat 14, then they take the full damage of the attack instead.<br />
<br />
===Spell Levels & Spells Per Day===<br />
The main section of the Spells page lists 10 sections, ranging from 0 to 9, representing the Cantrips (0) and spells level 1 - 9 where the level of the spell is listed in the triangle on the left of each section header. The number in the left square of the header represents the total number of Spell Slots, in other words, the maximum number of times a spell of this level can be cast in between long rests. This number will be set automatically depending on the level of your character, but can be modified by clicking the up or down arrow or just entering a number in the space provided. The number in the right-most box in the headers is the Slots Remaining value that can be used for you to keep track of the number of times you've cast a spell at this level.<br />
<br />
===Adding Spells===<br />
[[File:D&D5E-Roll20-Spells-Icons.png|framed|right]]<br />
When you drag spells from the <span style="font-family:Pictos;">i</span> [[Compendium]] to the sheet, a new spell entry will be added to the Spell Page under the appropriate level header. This will copy over all corresponding information linked to the spell, as well as creating an attack entry in the [[D%26D_5E_by_Roll20#.2811.29_Attacks_.26_Spellcasting|Attacks & Spellcasting]]-block on the "Core" page, if the spell can be used as an attack. The name of the spell will be listed to the left of the entry and to the right are icons for whether the spell is a Ritual (R), requires Concentration (C), and lists whether there is a Verbal (V), Somatic (S), or Material (M). There is also a circle at the far left of the entry that can be toggled to be filled in with red or left empty. This toggle represents spells that are Prepared for the day and are available for a player's convenience to help track this.<br />
<br />
You can manually add spells by selecting the <span style="font-family:Pictos;">&</span> under any of the Spell Level headings. This will present you with a blank template where you can enter all of the information about a spell. By default, the spell card only contains non-attack information about a spell. If the spell IS an attack you can change the "Output" selector from "Spellcard" to "Attack", this will show some additional input fields to fill out the attack information about the spell. Switching this input will also add an attack entry to the [[D%26D_5E_by_Roll20#.2811.29_Attacks_.26_Spellcasting|Attacks & Spellcasting]]-section on the [[#Core Page|Core page]] so this spell attack can also be cast from the main page. All of these sections are linked, so changing information in one place will also change the corresponding information in the other location. To save your edits, click on the gear icon at the upper right of the entry to collapse the spell entry.<br />
<br />
You can edit any spell at any time, by hovering your mouse over the entry to make a <span style="font-family:Pictos;">y</span> icon appear on the left. Clicking on the <span style="font-family:Pictos;">y</span> will roll out the spell once more to be edited.<br />
<br />
==Settings Page==<br />
[[File:D&D5E-by-Roll20-Settings-Page.png|thumb|right|400px|The Settings tab of the sheet, accessed from the '''<span style="font-family:Pictos;">y</span>''' icon ]]<br />
The Settings page, accessed by selecting the <span style="font-family:Pictos;">y</span>(gear) icon from the four buttons near the top right of the sheet, is where you can make changes to some parts of your character sheet that aren't represented on the other pages.<br />
<br />
===Class Options===<br />
In the class options section is where you have access to some important parts of your character, that usually are managed in the background. They are placed here so that, if needed they can be modified as well.<br />
<br />
'''Hit Dice:''' This section will be set automatically depending on the class chosen on the [[#Core Page|Core page]], but can be changed here by selecting the value and choosing a new one from the drop-down menu. This option is used whenever the "Hit Dice" section is used on the Core page.<br />
<br />
'''Carrying Capacity Modifier:''' This modifier allows you to increase the weight that a character can carry before they become encumbered.<br />
<br />
'''Global Magic Attack Modifier:''' This modifier will affect all spell attacks rolled from the sheet.<br />
<br />
'''Magic Caster Level:''' By default, a character's caster level is tethered to their class level. This option allows you to set the caster level manually, so you can have it differ from the character's class level. This will automatically change the Spell Slots Total for each spell level on the [[#Spell Page|Spells page]].<br />
<br />
'''Spell Save DC Mod:''' The Spell Save DC is normally a field you can't edit from the Spell page and is set by the character's class and level. This modifier allows you to alter that value.<br />
<br />
'''Spell Icons:''' This option will allow you to choose to turn off all the Spell Icons (R, C, V, S, & M), show them all, or only display only the ritual and concentration icons.<br />
<br />
'''Halfling Luck:''' Use this checkbox if your character is a Halfling that happens to take advantage of the Halfling Luck race feat. Using this feat will automatically re-roll any 1s rolled for attacks and skills or ability checks/saves.<br />
<br />
'''Arcane Fighter/Rogue:''' These checkboxes can be used to keep track of when your Fighter or Rogue-classed character actually has access to spells.<br />
<br />
===Multiclass Options===<br />
If you are taking advantage of the D&D 5E multiclassing you can keep track of it in this section. Any levels to your character's additional classes must be changed here, and will then be reflected in the header portion of the sheet. Once you've added additional classes in this section, any time you roll Hit Dice from the Core page it will ask you which classes hit dice you wish to use.<br />
<br />
Note: Be sure to not re-include your main class in this section, or your final level calculation will be incorrect.<br />
<br />
===Custom Class Options===<br />
If you are playing a class that is not part of the D&D 5E Compendium, you can input the important class information in this section, and checking the "Use Custom Class" checkbox will replace the main class selection with your custom built class.<br />
<br />
===Spell Slot Modifiers===<br />
This section allows you to manually modify how many spell slots your character has available for each spell level from 1 to 9.<br />
<br />
===Attribute Options===<br />
'''Attribute Modifiers:''' With this section you can manually adjust the individual Attribute Scores for Strength, Dexterity, Constitution, Intelligence, Wisdom, and Charisma.<br />
<br />
'''Initiative Modifier:''' Usually, your initiative modifier is just based off of your DEX modifier, but if you happen to find a magical item that enhances these rolls this is where you will put that bonus. This modifier will be used whenever the [[#.287.29_Armor_Class.2C_Initiative.2C_.26_Speed|Initiative]]-section is rolled on the Core page.<br />
<br />
'''Initiative Style:''' This setting allows you to select whether Initiative will be rolled with Advantage, Disadvantage, or rolled normally with a single d20 (default).<br />
<br />
'''Add DEX Tiebreaker to Initiative:''' If you would like to enable a tie breaker component to Initiative, this checkbox will enable adding your dexterity Attribute Score as a decimal value to your Initiative roll. So if you have a character with a dexterity attribute score of 14, your initiative modifier will change from a 2 to a 2.14.'<br />
<br />
'''Global Armor Class Modifier:''' This setting will modify your armor class and will be taken into account regardless of the equipment the character uses.<br />
<br />
'''Armor Class Tracking:''' There are three options available: The Automatic version that's default to the sheet where it adds 10 + your DEX modifer and then takes any armor equipped into account. A Custom version which expands out a formula upon selection where you can input your own formula for armor tracking, or you can turn Off Armor Tracking entirely. When turned off, you will need to manually adjust the Armor Class field on the Core page.<br />
<br />
===Save Options===<br />
'''Save Modifiers:''' With this section you can manually adjust the individual Save modifiers for Strength, Dexterity, Constitution, Intelligence, Wisdom, and Charisma.<br />
<br />
'''Death Save Modifier:''' A normal death save is usually just a D20 against a dc of 10, but if you're lucky enough to have a bonus to death saves, this is where you will put your bonuses. This modifier will be represented any time a "Death Save" is rolled from the Core page.<br />
<br />
'''Global Saving Throw Modifier:''' If you have an affect that would modify all saving throws, this option makes it easier to adjust your Save modifiers than having to go in and change each one individually. This modifier will be used every time any save is rolled from the sheet.<br />
<br />
===Skill Options===<br />
If your class offers the ability to achieve "Expertise" in a skill, or if you are using a Bard with the "Jack of All Trades" feat, this is where you will make these adjustments. There is also a section to add flat modifiers to any of your skills if your character has an archetype ability like Remarkable Athlete or a feat that adds a flat bonus to a skill. You can add expertise to any skill by clicking the value next to it and choosing "Expertise" from the drop-down menu. If your Bard has the Jack of All Trades feat, you can check the checkbox at the bottom of this section and it will automatically give half of your character's proficiency points to any skill check that doesn't have full proficiency.<br />
<br />
'''Passive Perception Modifier:''' This option will add a bonus to a character's Passive Perception which is not something you can change directly from the Core page of the sheet.<br />
<br />
===General Options===<br />
The General Options section has some important options that deal more with how the sheet works, rather than actual character creation. Most importantly, the NPC checkbox at the top, which will change the sheet to be the NPC version which is shaped to more easily track an NPC's information.<br />
<br />
'''Roll Queries - Always/Toggle/Query/Never Roll Advantage:''' This option will change how advantage is rolled for all attacks. It defaults to always roll advantage, which means that every time an attack is rolled it will roll twice and present the outcome of both rolls. This is useful for both advantage and disadvantage, otherwise you can just choose either the left or the right to be the default roll. Toggle adds a set of buttons at the top of the sheet to manually switch your advantage options between rolls. If Query is chosen, every time a roll is made it will ask you whether or not it's advantage. If Never is chosen, then it will always roll just a single dice per attack roll.<br />
<br />
'''Whisper Rolls to GM:''' Like above, you have the option to Never/Toggle/Query/Always whisper rolls to the GM. When this option is enabled, the attack roll will only be whispered to the GM and not made public.<br />
<br />
'''Auto Damage Roll:''' By default, damage rolls will not be rolled automatically, but only when you click the attack in the chat window. This is useful because you can choose to only roll damage when an attack hits. Using this option you can make the character always roll damage with every attack.<br />
<br />
'''Core Die Roll:''' You can change the core die (by default it is 1d20) to something else entirely here.<br />
<br />
'''Proficiency Bonus:''' By default, the character's Proficiency Bonus is calculated by class level. This setting allows you choose to calculate this bonus via By Level (the default), via a Proficiency Die as described in the Dungeon Master's Guide, or a Custom calculation which rolls out a field to enter a roll formula for the bonus.<br />
<br />
'''Global Save/Skill/Attack/Damage Modifier Field:''' This series of checkboxes will add new entries to the Saving Throws, Tools Proficiencies & Custom Skills, and Attacks & Spellcasting blocks respectively to add global modifiers (like if a character is under the effects of a Bless or Guidance spell). Each entry will have a Global label in grey at the bottom of its entry and a field to enter the modifier bonus. If you include a word in brackets with the bonus formula (ex. "1d4[Bless]"), the word enclosed in the brackets will appear when you mouse over a roll to see it's formula.<br />
<br />
'''Add Character Name to Templates:''' This option allows you to turn this on or off. When it is on, the character's name is listed in the roll template when rolls are made from the sheet. If the character sheet in question is for an NPC, you will likely want to have this off so the rolls don't accidentally show your hand of what sort of monster your party is facing. This setting is off by default.<br />
<br />
'''Auto Level Calculations:''' This option allows you to turn this on or off. When it is on, adjusting the character's class level will automatically update the character's proficiency bonus, Hit Dice, and spell Slot totals (if the class is a spellcaster).<br />
<br />
'''Encumbrance:''' This option dictates how encumbrance is handled on the Equipment block of the Core page. This requires your Inventory to be set to "Compendium Compatible" to automatically calculate and track the weight of your character's backpack if you enter the weight values for any of the items in your Equipment list. When your character becomes encumbered, and depending on its severity, the words ENCUMBERED, HEAVILY ENCUMBERED, or IMMOBILE will display in red underneath the TOTAL WEIGHT value. This setting has three options: Simple Encumbrance Rules, Variant Encumbrance Rules, or not follow Encumbrance rules at all by toggling it off from this.<br />
<br />
'''Inventory:''' With this option allows you to either have your Equipment block be "Compendium Compatible" or "Simple". The Simple version of the Equipment block will give you single text field to log your inventory. The Compendium Compatible version tracks weight, quantity, and attack options in an itemized list for every equipment item you add to the block.<br />
<br />
'''Features & Traits:''' This option can set the Features & Traits block to be either a single text field or a repeated section that will be Compendium Compatible to list traits and features in an itemized list.<br />
<br />
'''Proficiencies & Languages:''' This option can set the Proficiences & Languages block to be either a single text field or a repeated section that will be Compendium Compatible to list traits and features in an itemized list.<br />
<br />
'''Ammo Tracking (API Required):''' When using the 5th Edition OGL Companion API Script in your game (Pro Subscriber feature), you can set attacks to weapons using ammunition to automatically subtract from their tally in their Resource block. So if your character is equipped with a bow, rolling its attack will automatically remove an arrow from its Resource block.<br />
<br />
===Transition Options(outdated)===<br />
{{mbox | text = This feature doesn't seem to exist on the sheet any longer, so the info in this section is outdated}}<br />
<br />
If your campaign previously used the [https://wiki.roll20.net/DnD5e_Character_Sheet#Intro Community Contributed] or [https://wiki.roll20.net/index.php?title=DnD5e_Shaped_Character_Sheet&oldid=11112#General_Information Shaped Legacy] 5th Edition Character Sheets and you are swapping over to this one, we have an automated conversion tool that will clear or merge elements left over from those two sheets. This procedure can only be done ''once'' and can not be undone. It is recommended that you make a copy of your campaign first before attempting a sheet transition.<br />
<br />
There is also a checkbox that hides this feature entirely from the sheet. If you hide this by mistake, you can gain access to it again by creating a new character journal.<br />
<br />
=The NPC Sheet=<br />
''See Also:'' '''[[D&D5E by Roll20 NPC Attributes]]'''<br />
<br />
One of the most useful parts of the D&D 5E by Roll20 Character Sheet is that it contains both a PC sheet ''AND'' an NPC sheet. An NPC doesn't normally require the depth a PC sheet needs, so the NPC sheet is a much more slimmed down character sheet that doesn't require multiple pages like its PC counterpart. You can access this version of the sheet by going to the Settings Page, by clicking the gear icon near the top right of the sheet, and then checking the NPC checkbox. This will switch the sheet to the NPC version. You can switch back at any time by unchecking the NPC option under General Options on the new page.<br />
<br />
==NPC Options==<br />
[[File:5E_OGL_Sheet_NPC_Options.png|right|thumb|250px|The NPC Options Section]]This is the area where all of the NPC's stats will be entered, it covers everything from the NPC's name, to how strong or quick or smart it is, to what languages it speaks. Most of the fields in this section are just text fields used to keep track of information about the NPC. All of the information entered in these fields will be visible in the stat block once the NPC options are hidden. <br />
<br />
<br />
Any text that appears in light grey is placeholder text. It's there to offer you an example of what the content would be for any given field. <br />
<br />
By default, no skill or ability checks will show up in the NPC's stat block. Once you've added a value to the corresponding skill or ability save, they will appear. If for some reason the NPC will have to make a check with a skill or ability it does not have any bonus in, you can enter a 0 as the modifier for that check and it will add it to the list in the stat block below.<br />
<br />
The XP of an NPC auto-calculates based on its given challenge rating.<br />
<br />
If the NPC is a spellcaster, you can check the checkbox beside '''SPELLCASTING NPC''' and this will add a spell list section that utilizes the spell list and its functionality from the PC version of the sheet.<br />
<br />
At default, you can add Traits and Actions in their respective places after the Challenge Rating and XP area of the Stat Block. For Reactions and Legendary Actions, you need to enable them from the NPC Options section. For Reactions, check off the '''HAS REACTIONS''' checkbox. This will add a new sections to the Stat Block for you to add Reactions to. If an NPC is a monster with Legendary Actions then you must enter the number of actions that monster has access to each turn in the '''LEGENDARY ACTIONS:''' field. Once you add a number here, an additional section will appear in the stat block below, where you can add the specific legendary actions that the monster is able to do.<br />
<br />
The NPC sheet supports Compendium drag & drop. If you want to add a new monster to your game just drag the monster from the <span style="font-family:Pictos;">i</span> [[Compendium]]-tab of the [[Sidebar]] and drop it to anywhere on the Tabletop. This will automatically create a new journal entry named the same as the Compendium entry and will copy all of the information on that compendium page directly into the new sheet. If you have purchased any of the Compendium expansions that expands on the available NPCs like the Monster Manual or Volo's Guide to Monster, a token of that NPC will be added to the Tabletop that will have its stats automatically set and linked to the new journal entry.<br />
<br />
{{mbox | text = '''Note:''' If you already have a journal entry in your {{journal}}-tab with the exact same name as the <span style="font-family:Pictos;">i</span> [[Compendium]] entry, the drag and drop will not work as this automation will stop to prevent overwriting existing content the user has already created. If a drag and drop of an NPC Compendium page does not create a journal entry, run a search for that NPC's name in your Journal to see if an entry already exists. If you do not want to delete the older entry, renaming it will allow the drag and drop to work as expected.}}<br />
<br />
===General Options===<br />
Within the NPC Options section, directly below the Legendary Actions field, is the General Options that are featured on the PC Sheet: NPC checkbox, WHISPER ROLLS TO GM, and the AUTO DAMAGE ROLL options. <br />
<br />
*NPC checkbox<br />
*WHISPER ROLLS TO GM<br />
*AUTO DAMAGE ROLL<br />
*NPC NAME IN ROLLS<br />
*ADD DEX TO TIEBREAKER TO INITIATIVE<br />
<br />
Unchecking the NPC checkbox from here will revert the sheet back to the PC Sheet.<br />
<br />
===Hiding NPC Options===<br />
Once all of the desired information has been entered, you can click the <span style="font-family:Pictos;">y</span>(gear) icon at the top right to hide this section. This leaves behind just the NPC's stat block where you can make all of your rolls from. You can re-open this section to edit the information at any time by clicking on the <span style="font-family:Pictos;">y</span> icon again. It's in the same location regardless if you're looking at NPC Options or the NPC stat block.<br />
<br />
==The NPC Stat Block==<br />
[[File:5E OGL Sheet NPC v2.png|right|thumb|250px|An NPC stat block for a griffon]]Following NPC Options is the NPC Stat Block that is built off of what you input in the NPC Options section. This area may look very similar to a stat block you may find in a monster bestiary or published adventure.<br />
<br />
<br />
Any section of the stat block that has a corresponding roll will have click-able text. For example, if the NPC has to make a CON check, you can click the CON attribute to roll a CON check with all of the required modifiers automatically included. If you added a value to one of the skill modifier fields then that skill will show up in the NPC's "Saving Throws" list where you can click it to make a saving throw roll using that skill's modifier.<br />
<br />
The first section of the Stat Block mirrors all the information you added in the NPC Options section. This content is meant exclusively for rolling and can not be edited directly. You will need to change them from the NPC Options section.<br />
<br />
===Traits===<br />
Traits are pieces of information about an NPC that isn't covered by the NPC options section. These are entered directly onto the NPC's stat block. If you click the "<span style="font-family:Pictos;">&</span>" button that appears right below the "Senses/Languages/Challenge Rating" section it will add a blank entry where you can add a single trait for that NPC. Each Trait Entry features a bold title field which is then followed by a larger text box for the description of the trait. You can add any number of Traits for any NPC.<br />
<br />
===Actions===<br />
NPC actions can be used for any number of things. Each entry initially offers an Action Name field as well as a large text field for the Action description. The checkbox for ATTACK, once checked, adds more structured data fields needed for an attack roll (Type, Range/Reach, To Hit bonus, Target, Damage Roll, and Damage Type). To add a new entry you will select the <span style="font-family:Pictos;">&</span> button that appears below the Actions section. Once all of this is complete you can click the <span style="font-family:Pictos;">y</span>(gear) icon at the top of this entry to hide the input fields, leaving just the action text. You can show this information, or roll the attack, in the chat box by clicking the text for the action. If you need to make further modifications to any action you can hover over the row you wish to edit, then click on the <span style="font-family:Pictos;">y</span>(gear) icon again. This will show all of the action information input fields again. You can add any number of Actions for any NPC.<br />
<br />
===Bonus Actions===<br />
NPC bonus actions are typically not listed on the sheet, and are usually referenced in the Traits section. However, if a player wishes to use this section, it is available if the 'Bonus Action' checkbox is selected. The fields work the same as the Actions section.<br />
<br />
===Reactions===<br />
Once enabled from the NPC Options section, a new heading labeled "Reactions" and its relevant section is added to the stat block that allows you to add Reactions. These entries operate just like Traits.<br />
<br />
===Spells===<br />
Once enabled from the NPC Options section, a new heading labeled "Spells" and its relevant section is added to the stat block that allows you to add Spells. These entries will operate identically to how Spells are added and handled on the PC Sheet with the one noted exception that there is only a single column of spell entries. You can drag spells from the Compendium to add spell entries just like you would with the PC's Spell sheet. Any and all spells added to the character sheet are shared between the NPC and the PC versions.<br />
<br />
===Legendary Actions===<br />
If a number value is added to the LEGENDARY ACTIONS field in the NPC Options section, the Legendary Actions heading and section is added at the very bottom of the stat block and lists some verbiage on how many actions are available to be used on a given turn. This number is dictated by what you entered in the NPC Options. These entries operate the same way as Traits.<br />
<br />
==Rolling for Initiative for NPCs==<br />
There are two ways to roll for Initiative on the NPC sheet. You can click on the NPC's Name to roll for Initiative or you can roll from the die icon labeled INIT that is listed to the right of the Armor Class and Hit Points section of the NPC sheet, towards the top. If you have the Turn Tracker tool open, having the NPC token selected while rolling Initiative will automatically add the NPC and its initiative roll to the tracker. Creatures on the GM layer that are added to the tracker in this fashion will have their entries hidden from the players.<br />
<br />
<br />
You can also create a global Macro that will pop up as a Token Action button in the upper left hand corner of the tabletop every time a token is selected. This will allow you to roll without looking at the NPC sheet at all. The macro formula should look just like this:<br />
<br />
<code>%{selected|npc_init}</code><br />
<br />
=Advanced Use=<br />
<br />
===Custom Skills and Stats===<br />
You can set up any number of custom skills or rolls from the [[#Tool Proficiencies|Tool Proficiencies]] section just underneath the skill section on the Core tab. [[#Class & Other Resources|The Resources]] section is also useful for tracking custom stats to your campaign, game setting, or home-brew rules. There are also various options available from the Settings page to modify attributes, skills, saves, spells, and more.<br />
<br />
===Target Roll Buttons===<br />
A useful way for GMs and Players to reference their abilities is by dynamically setting up a handful of macros that can be used on a token linked to a character, rather than having to roll directly from the sheet. To do this, you'll set up a global macro from the {{Collections}}-tab. You can also write these directly in the {{Text Chat}}.<br />
<br />
In the examples, the <code>selected</code> part can be replaced with <code>target</code>, a character's name, or it's character ID.<br />
<br />
Here are some examples:<br />
<br />
'''PC'''<br />
* Attributes: <code>%{selected|strength}</code>, <code>%{selected|strength_save}</code> | Will roll the Strength Check and Strength Save for the selected [[token]](if the [[Link Token|token is linked to a sheet]])<br />
* <code>%{selected|acrobatics}</code><br />
* <code>%{selected|initiative}</code><br />
* <code>%{selected|death_save}</code><br />
* <code>%{selected|hit_dice}</code><br />
<br />
'''NPC'''<br />
* <code>%{selected|npc_init}</code><br />
* <code>%{selected|npc_str}</code><br />
* <code>%{selected|npc_stealth}</code><br />
* <code>%{selected|npc_hpformula}</code><br />
====Rolling from Repeating Sections====<br />
The example we'll be using today is setting up the 1st NPC action:<br />
<code>%{selected|repeating_npcaction_$0_npc_action}</code><br />
Now whenever you use this macro it will roll the first NPC action of whichever NPC token you have selected. You can set up a roll for each action by incrementing the 0 by 1 for each action you wish to add (I.E. <code>$1</code>, <code>$2</code>, <code>$3</code>). Here is a list of important repeating section rolls and their formulas:<br />
<br />
* Player Attack/Spell Attack <code>%{selected|repeating_attack_$0_attack}</code><br />
* Player Attack/Spell Damage <code>%{selected|repeating_attack_$0_attack_dmg}</code><br />
* Player Attack/Spell Critical Damage <code>%{selected|repeating_attack_$0_attack_crit}</code><br />
* Player Global DMG mod <code>%{selected|repeating_damagemod_$0_global_save}</code><br />
** Attr names: <code>global_damage_name</code>, <code>global_damage_damage</code>, <code>global_damage_critical_damage</code>, <code>global_damage_type</code><br />
* Proficiencies <code>%{selected|repeating_proficiencies_$0_output}</code><br />
* Tool/Custom Skill <code>%{selected|repeating_tool_$0_tool}</code><br />
* Traits/Feats: <code>%{selected|repeating_traits_$0_output}</code><br />
<br />
* Spellbook Cantrip <code>%{selected|repeating_spell-cantrip_$0_spell}</code><br />
* Spellbook Level 1 <code>%{selected|repeating_spell-1_$0_spell}</code><br />
* Spellbook Level 2 <code>%{selected|repeating_spell-2_$0_spell}</code><br />
* Spellbook Level 3 <code>%{selected|repeating_spell-3_$0_spell}</code><br />
* Spellbook Level 4 <code>%{selected|repeating_spell-4_$0_spell}</code><br />
* Spellbook Level 5 <code>%{selected|repeating_spell-5_$0_spell}</code><br />
* Spellbook Level 6 <code>%{selected|repeating_spell-6_$0_spell}</code><br />
* Spellbook Level 7 <code>%{selected|repeating_spell-7_$0_spell}</code><br />
* Spellbook Level 8 <code>%{selected|repeating_spell-8_$0_spell}</code><br />
* Spellbook Level 9 <code>%{selected|repeating_spell-9_$0_spell}</code><br />
<br />
'''NPC'''<br />
* NPC Traits/Abilities<code>%{selected|repeating_npctraits_$0_npc_roll_output}</code><br />
* NPC Actions/Attacks<code>%{selected|repeating_npcaction_$0_npc_action}</code><br />
* NPC Attack Damage<code>%{selected|repeating_npcaction_$0_npc_dmg}</code><br />
* NPC Attack Critical Damage<code>%{selected|repeating_npcaction_$0_npc_crit}</code><br />
* NPC Bonus Actions<code>%{selected|repeating_npcbonusaction_$0_npc_action}</code><br />
* NPC Legendary Actions<code>%{selected|repeating_npcaction-l_$0_npc_action}</code><br />
* NPC Mythic Actions<code>%{selected|repeating_npcaction-m_$0_npc_action}</code><br />
* NPC Spells<code>%{selected|repeating_spell-npc_$0_spell}</code><br />
<br />
===Directly Referencing Attributes===<br />
You can discover the name of most of the attributes in the sheet by hovering over them. After a couple of seconds a title will pop up and tell you how to referencing them. You can call attributes in an Ability Rolls by using <code>@{attributename}</code>. If you want to directly reference it in a roll that isn't saved on the sheet, you need to specify the character's name, or use either the <code>selected</code> or <code>target</code> key works.<br />
<br />
'''Examples:'''<br />
* <code>/em attempts to grapple and gets [[1d20+@{strength_mod}]]</code> custom [[Journal#Attributes_.26_Abilities_Tab|Ability call]], saved in the "attributes and abilities" tab of the character sheet.<br />
* <code>/r 1d20+@{Alice|strength_mod}+@{Alice|pb}</code> macro that calls a specific character<br />
* <code>/em have @{selected|hp} out of @{selected|hp|max} left.</code> macro that uses stats from a token(token must be selected before rolling)<br />
* <code>The Enemy's AC is @{target|npc_ac}</code> macro prompt the user to select a target token on the map, and uses it's stats.<br />
<br><br />
<br />
See [[Macros#Attribute_Macros]] for further general details/examples on the syntax.<br />
====PC====<br />
Here are a list of some of the more important stats:<br /><br />
<br />
'''Attributes/Saves'''<br />
<br />
* Str: <code>strength, strength_mod, strength_save_bonus</code><br /><br />
* Dex: <code>dexterity, dexterity_mod, dexterity_save_bonus</code><br /><br />
* Con: <code>constitution, constitution_mod, constitution_save_bonus</code><br /><br />
* Int: <code>intelligence, intelligence_mod, intelligence_save_bonus</code><br /><br />
* Wis: <code>wisdom, wisdom_mod, wisdom_save_bonus</code><br /><br />
* Cha: <code>charisma, charisma_mod, charisma_save_bonus</code><br />
<br><br />
'''Skills'''<br />
<br />
<code>athletics_bonus<br /><br />
acrobatics_bonus<br /><br />
animal_handling_bonus<br /><br />
arcana_bonus<br /><br />
deception_bonus<br /><br />
history_bonus<br /><br />
insight_bonus<br /><br />
intimidation_bonus<br /><br />
investigation_bonus<br /><br />
medicine_bonus<br /><br />
nature_bonus<br /><br />
perception_bonus, passive_wisdom<br /><br />
performance_bonus<br /><br />
persuasion_bonus<br /><br />
religion_bonus<br /><br />
sleight_of_hand_bonus<br /><br />
stealth_bonus<br /><br />
survival_bonus<br /><br />
</code><br />
<br />
'''AC, Proficiency, HD etc'''<br />
<br />
<code>pb</code>(Proficiency Bonus)<br><br />
<code>inspiration</code><br><br />
<code>ac<br /><br />
initiative_bonus<br /><br />
speed<br /><br />
hp, hp|max, hp_temp<br /><br />
hit_dice, hit_dice|max, hitdietype<br /><br />
weighttotal<br /><br />
</code><br />
<br />
'''Spells, in general'''<br><br />
<br />
These are individual attributes that you can access, that contain information on a character's spellcasting capabilities in general.<br><br />
<br />
<code>spell_save_dc</code><br><br />
<code>spell_attack_bonus</code><br><br />
<br />
<code>lvl1_slots_total</code><br><br />
<code>lvl1_slots_expended</code><br><br />
<br />
<code>lvl2_slots_total</code><br><br />
<code>lvl2_slots_expended</code><br><br />
<br />
<code>lvl3_slots_total</code><br><br />
<code>lvl3_slots_expended</code><br><br />
<br />
<code>lvl4_slots_total</code><br><br />
<code>lvl4_slots_expended</code><br><br />
<br />
<code>lvl5_slots_total</code><br><br />
<code>lvl5_slots_expended</code><br><br />
<br />
<code>lvl6_slots_total</code><br><br />
<code>lvl6_slots_expended</code><br><br />
<br />
<code>lvl7_slots_total</code><br><br />
<code>lvl7_slots_expended</code><br><br />
<br />
<code>lvl8_slots_total</code><br><br />
<code>lvl8_slots_expended</code><br><br />
<br />
<code>lvl9_slots_total</code><br><br />
<code>lvl9_slots_expended</code><br><br />
<br />
<br />
'''Spells, repeating sections'''<br><br />
<br />
These are sections, which means that each of them contains several attributes that you can access. For example, "repeating_spell-1" is a section that contains all the attributes that relate to a character's 1st-level spells.<br><br />
<br />
<code>repeating_spell-cantrip</code><br><br />
<code>repeating_spell-1</code><br><br />
<code>repeating_spell-2</code><br><br />
<code>repeating_spell-3</code><br><br />
<code>repeating_spell-4</code><br><br />
<code>repeating_spell-5</code><br><br />
<code>repeating_spell-6</code><br><br />
<code>repeating_spell-7</code><br><br />
<code>repeating_spell-8</code><br><br />
<code>repeating_spell-9</code><br> <br />
<br />
'''Spells, about the attributes within those repeating sections'''<br><br />
<br />
Building on our previous example from the sections, if you start with "repeating_spell-1", and then add "_$0" to the end of it, then now you're referring to the topmost spell in your list of 1st-level spells. And, if you then add an attribute name (see the list of attribute names here below), then you can narrow your reference even further. For example, if you use "repeating_spell-1_$0_spellname", then you are referring to the name of the aforementioned spell. And if you add "_spellrange" instead of "_spellname", then you are now referring to the range of the aforementioned spell.<br><br />
<br />
'''Spells, list of attribute names, for the repeating sections'''<br><br />
<br />
<code>spellname</code><br><br />
<code>spellrange</code><br> <br />
<code>spellcastingtime</code><br><br />
<code>spelltarget</code><br><br />
<code>spellduration</code><br><br />
<code>spellschool</code><br><br />
<code>spellritual</code><br><br />
<code>spellconcentration</code><br><br />
<code>spellcomp_v</code><br><br />
<code>spellcomp_s</code><br><br />
<code>spellcomp_m</code><br><br />
<code>spellcomp_materials</code><br><br />
<code>spell_ability</code><br><br />
<code>spelloutput</code><br><br />
<code>spellattack</code><br><br />
<code>spelldamage</code><br><br />
<code>spelldamage2</code><br><br />
<code>spelldamagetype</code><br><br />
<code>spelldamagetype2</code><br><br />
<code>spellhealing</code><br><br />
<code>spelldmgmod</code><br><br />
<code>spell_damage_progression</code><br><br />
<code>spellsave</code><br><br />
<code>spellsavesuccess</code><br><br />
<code>spelldescription</code><br><br />
<code>spellclass</code><br><br />
<code>spellsource</code><br><br />
<code>spellprepared</code><br><br />
<br />
'''Items'''<br><br />
<code>cp sp ep gp pp</code><br><br />
(copper pieces, silver, gold, electrum, platinum)<br />
<br />
<code>repeating_inventory_$#_itemcount<br><br />
repeating_inventory_$#_itemname<br><br />
repeating_inventory_$#_itemweight<br><br />
repeating_inventory_$#_equipped<br><br />
repeating_inventory_$#_useasresource<br><br />
repeating_inventory_$#_hasattack<br><br />
repeating_inventory_$#_itemproperties<br><br />
repeating_inventory_$#_itemmodifiers<br><br />
repeating_inventory_$#_itemcontent</code><br><br />
<br />
* <code>equipped</code>, <code>useasresource</code>, <code>hasattack</code> are checkboxes, with value 1 if checked.<br />
* <code>itemmodifiers</code> is for of item changes any stats, like <code>AC +2</code> adding +2 to AC when equpped.<br />
* <code>itemcontent</code> is the item description<br />
<br><br />
'''The class_resource and the other_resource'''<br><br />
<br />
The resources <code>class_resource</code> and <code>other_resource</code> are static resources. That is to say, you need to keep in mind that they are NOT a part of the repeating section, even though it definitely looks that way on the character sheet.<br><br />
<br />
You use these to access them<br />
<br />
<code>class_resource</code><br><br />
<code>class_resource_max</code><br><br />
<code>class_resource_name</code><br><br />
<code>other_resource</code><br><br />
<code>other_resource_max</code><br><br />
<code>other_resource_name</code><br><br />
<br />
'''The repeating resources'''<br><br />
<br />
Any resources that appear beneath the "class resource" and the "other resource" are a part of the "repeating resources" section. This section is known for being confusing for beginners, so it deserves a bit of clarification.<br />
<br />
First, keep in mind that this is one section (not two sections, as people often think), and that "repeating_resource" is its section prefix.<br />
<br />
Second, keep in mind that you need to skip past the row with the "class resource" when you're figuring out the address of the row that you want to refer to. So basically, if you want to refer to the row that is directly below the row with the "class_resource", then you would add "_$0" (to form "repeating_resource_$0"). And then the next row after that is "_$1", and so on.<br />
<br />
Third, keep in mind that if you add "_resource_left" (to form "repeating_resource_$0_resource_left"), then you are specifying that you are talking about the CURRENT VALUE of the leftmost resource in that row. And if you add "_resource_left_max", then you are specifying that you are talking about the MAX VALUE of the leftmost resource in that row.<br />
<br />
Here is a complete list of all the fields that you can access in the "repeating_resource" section. Just replace the "#" character with which row you want to access.<br />
<br />
<code>repeating_resource_$#_resource_left</code><br><br />
<code>repeating_resource_$#_resource_left_max</code><br><br />
<code>repeating_resource_$#_resource_left_name</code><br><br />
<code>repeating_resource_$#_resource_right</code><br><br />
<code>repeating_resource_$#_resource_right_max</code><br><br />
<code>repeating_resource_$#_resource_right_name</code><br><br><br />
<br />
<br />
'''Features/Class Traits'''<br />
<br />
<code>repeating_traits_$0_output<br><br />
repeating_traits_$#_name<br><br />
repeating_traits_$#_source<br><br />
repeating_traits_$#_source_type<br><br />
repeating_traits_$#_description<br><br />
</code><br />
<br />
'''Other/Settings'''<br />
<br />
<br><br />
<code><nowiki>wtype</nowiki></code> (whisper type, can have one of these values:)<br />
* <code><nowiki></nowiki></code> (empty for never whisper)<br />
* <code><nowiki>@{whispertoggle}</nowiki></code> (show the buttons on sheet that can toggle between options)<br />
* <code><nowiki>?{Whisper?|Public Roll,|Whisper Roll,/w gm }</nowiki></code><br />
* <code><nowiki>/w gm</nowiki></code> (always whisper)<br />
<br />
<br />
'''Global modifiers'''<br />
<br />
* <code>repeating_savemod_$0_global_save_roll</code><br />
* <code>repeating_skillmod_$0_global_skill_roll</code><br />
* <code>repeating_tohitmod_$0_global_attack_roll</code><br />
* <code>repeating_damagemod_$0_global_damage_damage</code><br />
<br />
====NPC====<br />
Some stats are the same as for PCs<br />
<br />
<code>npc_name<br><br />
npc_ac<br><br />
hp, hp|max<br><br />
npc_speed<br><br />
npc_challenge<br><br />
npc_xp</code><br />
<br />
Attributes: <code>strength_base, strength_mod</code> (same as PCs)<br />
Saves:<br />
<br />
<code>npc_str_save_base</code>,<code>npc_dex_save_base</code>, <code>npc_con_save_base</code>,<code>npc_int_save_base</code>,<code>npc_wis_save_base</code><code>npc_cha_save_base</code><br />
Skill bonus:<code>npc_acrobatics_base</code>, <code>npc_animal_handling_base</code> etc.<br />
<br />
Damage/Conditions stuff:<br />
<br />
<code>npc_vulnerabilities<br><br />
npc_resistances<br><br />
npc_immunities<br><br />
npc_condition_immunities</code><br />
<br />
Spells:<br />
<br />
<code>npcspellcastingflag</code> (set to "1" if caster, empty otherwise) <br />
<code>spellcasting_ability</code><br />
<code>globalmagicmod </code> (global magic attack modifier)<br />
<code>caster_level</code><br />
<code>spell_dc_mod</code> (spell save DC mod)<br />
<br />
Spells are identical to PC section<br />
<br />
Other:<br />
whisper is same as PCs<br />
<br />
<code>npc_name_flag</code> (show/hide npc name in rolls, value is either <code><nowiki>{{name=@{npc_name}}}</nowiki></code> or <code>0</code>)<br />
<br />
<br />
<sup>Note: anything with the Suffix of <code>|max</code> requires some form of Prefix, such as <code>selected|</code> making the call for such a thing look something along the lines of <code>@{selected|hp|max}</code>. The <code>|max</code> Suffix specifically calls the box on the right of the selected Attribute's Line, for example, you could fill in the Weight Total's 2nd Box with <code>@{strength}*15</code> & whenever you call <code>@{selected|weighttotal|max}</code> it will tell you your 5e standard Maximum Carry Capacity for your current Strength Score.<br />
<br />
===Custom AC Items===<br />
You can add pieces to your inventory and manually give them AC or magic bonuses that will figure into their calculations automatically. Inside the item options is a section for "MODS:". Add <code>Ac +1</code> to add an armor class bonus.<br />
<br />
===Roll Templates===<br />
''Main Article:'' '''[[D&D 5e by Roll20 Roll Templates]]'''<br />
<br />
The '''D&D5E by Roll20''' Character Sheet also includes a series of [[Roll Templates]] that you can use to dress up your own custom macros. Roll Templates provide additional layout and styling options for the display of roll results.<br />
<br />
{{ex}}<br />
[[File:5e-rolltemplate-ex1-2021.png|200px|right|none]]<br />
Rolls stealth for selected npc token, using it's stealth proficiency.<br />
<code><nowiki>/w gm &{template:npcatk} {{attack=1}} {{name=Shadow}} {{rname=Shadow Stealth}} {{rnamec=Hide}} {{r1=[[@{selected|d20}+@{selected|npc_stealth} + 6]]}} {{always=1}} {{r2=[[@{selected|d20}+@{selected|npc_stealth} + 6]]}} {{description=While in dim light or darkness, the shadow can take the Hide action as a bonus action. Its stealth bonus is **also** improved to +6 }}</nowiki></code><br />
<br />
===Magic Missile Spell===<br />
{| role="presentation" class="wikitable mw-collapsible mw-collapsed" style="float:right; margin-left: 10px;margin-right: 60px;"<br />
| Image of the Spell's settings<br />
|-<br />
| [[File:Magic-Missile-5E-2020.png|right|frame|The Magic Missile Spell]]<br />
|}<br />
<br />
RAW, Magic Missile is rolled once, and the single roll is then used for each hit. So by default the spell rolls <code>1d4+1</code>. (See [[Talk:D&D 5E by Roll20#Old Magic Missile Discussion]] for more info.)<br />
<br />
You can modify the spell to instead roll 3d4+3 at first level, and then in the ''HIGHER LVL CAST DAMAGE'' section, set it to <code>1d4+1</code>.<br />
<br />
To automatically use higher-level spell slots with Magic Missile, you have to write a 0 into the ''HIGHER LVL CAST DAMAGE'' section of the spell and select any die. It will show the box for selecting higher-level spell slots when launching Magic Missile, but since it multiplies the higher-level damage cast by 0, the added roll doesn't show up in the chat, making it roll a single die for every missile while using any level spell slot.<br />
<br />
=API=<br />
{{pro only|section}}<br />
[[API:Introduction|API Scripts]] allow for greater customization and functionality to how Roll20 operates beyond what it can do at default. This section will list some info on using various APIs that interact with the character sheet.<br />
<br />
Example of APIs from the One-Click Install menu, that designed to be used with the '''D&D 5E by Roll20''' sheet:<br />
* '''5E BattleMaster'''<br />
* '''5E Resting in Style'''<br />
* '''CashMaster'''<br />
* '''Concentration'''<br />
* '''[[Script:It's a Trap|It's a Trap! -- D&D 5E Generic]] (should detect automatically what sheet is used)<br />
** {{repo|Roll20/roll20-api-scripts/tree/master/ItsATrap_theme_5E_Generic#readme readme}}<br />
* '''ShortRest'''<br />
* '''SpellMaster'''<br />
* '''WildShape'''<br />
<br />
A good number of the more general APIs have built in settings for configuring them for usage with the 5E sheet, such as '''GroupInitiative''', '''GroupCheck''', '''Experience Tracker''', '''[[PowerCards]]''', '''[[ScriptCards]]''' (ScriptCards is an improved version of PowerCards)<br />
<br />
* '''[[GroupCheck]]:''' <code>!group-check-config --import 5E-OGL</code> will configure the API for use with this sheet<br />
* '''[[GroupInit|GroupInitiative]]:''' before use, API need to be configured for the sheet, either through the menu preset, or using the command: <code>!group-init --add-group --Bare </code><br />
* '''CombatMaster:''' is by default configured with conditions for D&D 5E<br />
* '''[[ChatSetAttr]]:''' API that can create, edit, & delete stats on sheets. Example: [[Script:ChatSetAttr#Add_new_thing_to_Repeating_Section|Adding a new magic item to a sheet]], with one chat command <br />
* '''[[Script:Ammo]]''' can be used for updating ammo & spellslots when used<br />
<br />
==Utilizing the ''5th Edition OGL by Roll20 Companion'' API Script==<br />
'''{{repo|Roll20/roll20-api-scripts/tree/master/5th%20Edition%20OGL%20by%20Roll20%20Companion 5th Edition OGL Companion}}'''is an official companion script for the "D&D 5E by Roll20" character sheet. The Companion currently supports Ammo Tracking, Automatic NPC Tokens, Automatic Death Save Tracking, and Automatic Spell Slot Tracking. <br />
<br />
{{mbox | text = Installing & creating [[API]] Scripts is a {{Pro}} feature. In order to be able to access these advanced scripts, the [[GM]] of the campaign must be a [[Pro]] subscriber and enable it for their campaign.}}<br />
<br />
<br />
'''''How to Add the API Script to your Game'''''<br />
<br />
If you have a PRO account, you can install the API script by going to your game's Campaign Page and clicking on the '''Settings''' button, and then choosing '''API Scripts'''. This brings you to the API Scripts page for your current game. The Companion Script is part of the One-Click Community API Installation options. Under the Script Library tab, there is a drop down menu that lists all the available community created scripts. Scroll down till you find the '''System Toolbox''' category and select the "5th Edition OGL by Roll20 Companion" script. The version number, the script's author, and a brief description of what the script does will appear right below the drop down menu once it is selected. Below that, click on the blue "Add Script" button to add the script to your game.<br />
<br />
<br />
'''''List of API commands for the 5th Edition OGL Companion API Script'''''<br />
* <code>!5ehelp</code> - Gives a list of the script's API commands in the chat tab.<br />
* <code>!5estatus</code> - Lists the current status of the script's features in the chat tab.<br />
* <code>!ammotracking on/off/quiet</code> - Automatically expends linked resource when attack is made<br />
* <code>!autonpctoken on/off</code> - Automatically generates a NPC token on the GM's screen based on the default token when an NPC's health calculation is rolled<br />
* <code>!deathsavetracking on/off/quiet</code> - Automatically ticks off successes and failures when death saves are rolled, clearing on death, stabilization, or hp recovery<br />
* <code>!longrest <character name></code> - This will add Hit Dice recover and if spelltracking is on, this command will reset all of the character's spell slots to unspent.<br />
* <code>!npchp <character name></code> - Rolls NPC hit point totals using their formula and updates the token bar. If no character name is provided it will roll the selected tokens.<br />
* <code>!spelltracking on/off/quiet</code> - Automatically expends spell charges as cast, factoring in higher level casting, and spells marked as Rituals will not spend a spell slot.<br />
<br />
<br />
Options:<br />
* ''on'' - Toggles the functionality on (default)<br />
* ''off'' - Disables the functionality<br />
* ''quiet'' - Maintains functionality while preventing results from being output to the chat.<br />
<br />
<br />
===Automatic Ammunition Tracking===<br />
''Main Article:'' '''[[D&D 5E by Roll20: How to setup Ammunition and Resource tracker]]'''<br />
<br />
Automatic Ammunition Track is a feature that requires the above Companion API Script. Once installed, follow these instructions to enable automatic ammunition tracking in your game:<br />
<br />
This example sets up a Longbow with a quiver of Arrows to track.<br />
# On the Settings (Gear Icon) tab of a character sheet, under GENERAL OPTIONS, make sure that the INVENTORY option is set to "Compendium Compatible" and not "Simple".<br />
# While still under GENERAL OPTIONS, set the AMMO TRACKING feature to ON.<br />
# Create manually or drag a missile weapon (ex. Longbow) from the Compendium to your sheet.<br />
# Create manually or drag a missile type (Arrows) from the compendium to your sheet<br />
# Expand the missile type (Arrows) by clicking on the "I" information icon that appears when hovering the mouse over the item.<br />
# Select the USE AS RESOURCE checkbox. (ammunition items dragged from the Compendium will have this option automatically checked off)<br />
# On the CORE tab, expand the missile weapon (Long Bow) in the ATTACKS & SPELLCASTING section by clicking on the gear icon that appears when hovering over the attack.<br />
# In the AMMUNITION section put the exact name of the ammunition resource (Arrows). If you want to spend more than one piece of ammunition per shot you want to add the number of pieces after the name of the ammunition resource and a comma. (ex. ''Arrows,2'' )<br />
<br />
<br />
Now, any time the missile weapon (Longbow) is rolled, a piece of ammunition will automatically be spent and the chat will make note. Additionally after the first time the missile weapon is used the AMMUNITION section will update with the ID of the resource repeating section, this is normal and expected.<br />
<br />
<br />
===Automatic Spell Slot Tracking===<br />
<br />
Automatic Spell Slot Tracking is a feature that requires the above Companion API Script. Once installed, follow these instructions to enable automatic spell slot tracking in your game:<br />
* In the chat input area of the Sidebar, type ''!5estatus'' and press Enter, to check if spelltracking is set to 'on'.<br />
* If not, type ''!spelltracking on'' and press Enter to activate this feature.<br />
* Alternatively, you may type ''!spelltracking quiet'' and press Enter to activate this feature, while preventing spelltracking messages from being displayed in the chat.<br />
<br />
<br />
<br />
Once the Spell Slot Tracking has been activated, each time a spell is cast:<br />
# The number of cast spells of the appropriate level is updated in the Spell tab of the character sheet (see [[5th Edition OGL by Roll20|Spell Levels & Spells Per Day]]).<br />
# A message is output in the chat, displaying the spell level, the number of available spell slots and the number of used spell slots for this level.<br />
# Spell slots decrement as spells are cast. <br />
# Spells that are marked as a Ritual do not affect the tally of spell slots when cast.<br />
<br />
<br />
At any time, you can manually adjust this count directly in the Spell Page of the character sheet.<br />
<br />
=Updates=<br />
* {{hc|articles/360037772613-Change-Log Roll20 Changelog}} - Full Changelog of Roll20, updates for 5E sheet are included<br />
* {{fpl|10096810/ D&D 5th Edition by Roll20 (Q2Y2021)}} often has mentions of latest updates<br />
* Major Sheet Updates:<br />
** Feats can now be selected in Charactermancer {{fpl|8891809 June 2020}}<br />
** Game [[creator]] can select which [[compendiums]] are or aren't accessible in a game. [https://app.roll20.net/forum/post/8738570/release-note-for-may-26-2020 May 26 2020]<br />
<br />
=Known Issues=<br />
The sheet has a number of known bugs and issues, some which are mentioned in the sheet's latest forum thread.<br />
<br />
'''Charactermancer/Character Creation'''<br />
* '''Charactermancer & Compendium drag-n-drop doesn't work when sheet is in a separate window.''' This is [[Character_Sheets#Character_Sheet_in_a_separate_window|an inherit limitation to how character sheets work]] at the moment. <br />
* '''Multiclassing & spell selection''' - There are troubles when multiclassing spellcasters and getting to select spells from the right lists.<br />
* '''Duplicate races/classes from Essential Kit appear in selection''' You need to uncheck EK from your compendium for it to no longer appear in selections.<br />
<br />
<br />
'''General:'''<br />
* '''Warlock spell slots''' - The Warlock's spell slots don't work too well with the sheet, and most people use some manual adjustments for how they work. The number of spell slots also appears wrong in the Charactermancer.<br />
* '''NPC stat <code>desc</code> changed into <code>description</code>''' This was a recent update that broke some macros for people, resulting in error messages along: "can't find ''desc'' attribute" {{fpl|8297517/ release notes march 2020}}<br />
<br />
=Sheet Guides=<br />
* [[5E Macros]]<br />
* {{blog|638339117446578176/tome-of-tips-dungeons-dragons-5th-edition-ogl Tome Of Tips: The D&D 5E character sheet}}<br />
* {{yt.be|9BGGr97qJdY|Learning Roll20: EP01 Character Sheets (D&D 5E)}} 50min, by Roll20 (2020)<br />
<br />
=Related Pages=<br />
* D&D 5E by Roll20 sheet<br />
** [[D&D5E by Roll20 NPC Attributes]]<br />
** [[D&D 5e by Roll20 Roll Templates]]<br />
** [[D&D 5E by Roll20: How to setup Ammunition and Resource tracker]]<br />
* [[5E]] - general D&D 5E info for Roll20. Lists also the alterantive character sheets for 5E<br />
* [[D&D]] - Roll20 stuff on the various editions.<br />
* {{Compendium}}<br />
** [[Compendium Sharing]]<br />
* [[Character Vault]]<br />
<br />
=See Also=<br />
* {{repo|Roll20/roll20-character-sheets/tree/master/DD5thEditionLegacy Sheet sourcecode}} - (Public version of sheet code is 1½+ years behind from what is actually used)<br />
* {{hc|articles/360037772613-Change-Log Roll20 Changelog}} - Full Changelog of Roll20, updates for 5E sheet are included<br />
<br /><br />
<br /><br />
[[Category:Character Sheet Documentation]]<br />
[[Category:Official Sheet]]<br />
[[Category:DnD5E]]<br />
[[Category:Featured articles]]</div>5004103https://wiki.roll20.net/D%26D_5E_by_Roll20D&D 5E by Roll202021-10-12T17:33:25Z<p>5004103: /* PC */</p>
<hr />
<div>{{revdate}}{{HCbox|{{hc|360037773573-5th-Edition-OGL-by-Roll20 D&D 5E by Roll20}} }}<br />
[[File:5E OGL Sheet Core v2.6.png|500px|thumb|right|The '''D&D 5E by Roll20''' Character Sheet]]<br />
<br />
This is the community-driven documentation for the '''[[5E|D&D 5E]] by Roll20''' character sheet. Previously the sheet was known as the '''"5th Edition OGL Sheet"''' or just the '''"OGL Sheet"'''.<br />
<br />
=The Basics=<br />
This page is a ''[[Community Wiki]]'' guide to the Official D&D 5th Edition character sheet, which is updated with info tricks that might not be covered by the {{hc|articles/360037773573-5th-Edition-OGL-by-Roll20 official sheet documentation}}.<br />
<br />
<br />
To find out about the latest updates, issues and talk about the sheet, check the {{fpl|10096810/ D&D 5th Edition by Roll20 (Q2Y2021)}}-thread on the {{forum|category/277980 forums}}.<br />
<br />
<br />
[[Bug|Bug reports]] for the sheet is best reported in the same thread. If you find bugs in the 5E Compendium or 5E marketplace content, {{bug}}.<br />
<br />
<br />
__TOC__<br />
<br />
==Adding the Character Sheet to a Game==<br />
[[File:D&D5E-Roll20-sheet-selection.png|300px|thumb|right|The Sheet Selection Menu]]An official or community contributed character sheet [[Add_character_sheet#Adding_a_Character_Sheet_to_your_Campaign|can be added to any game when you first create it]]. On the Game Creation screen, underneath the large blue '''“I’m Ready, Create Game!”''' button, is the '''“Optional: Choose a Character Sheet”''' section. Located here is a drop down menu that lists all the character sheets built either by Roll20 officially or created by the community. These sheets are sorted under their respective RPG Systems in alphanumerical order. Once selected, a preview of the character sheet will load upon the creation page for you to review as well as showcase relevant information about the sheet, such as the sheet’s creator and its key features.<br />
<br />
<br />
The '''D&D 5E by Roll20''' Sheet can be found under either: '''Sheets by Roll20''' → D&D 5E by Roll20 OR '''Dungeons and Dragons 5E''' → D&D 5E by Roll20<br />
<br />
<br />
If you want to add a character sheet to an existing campaign, you can find this drop down menu once again by accessing the [[Game Settings Page]] from the [[Game_Management#Game_Details_Page|Game Details]]-page.<br />
<br />
{{mbox | text = '''NOTE:''' If you have added custom attributes to your character journals prior to adding a character sheet to a campaign, you may want to delete them first. Adding a character sheet to a campaign will create its own set of custom attributes on all of your character journals, but it will reuse any attributes encountered if they share the same name. This can cause calculation issues on the sheet.}}<br />
<br />
<br />
If you were previously using either the [[DnD5e Shaped Character Sheet|D&D 5E (Shaped)]] or [[DnD5E_Community_Contributed|D&D 5E (Community Contributed)]] sheets and wish to transfer over to the '''D&D 5E by Roll20''' version, it's a good idea to ask help on the [https://app.roll20.net/forum/category/277980 forums].<br />
<br />
<div style="clear: both"></div><br />
<br />
==Where to Find the Sheet==<br />
Once a character sheet has been added to a game, and once inside it, on all [[Journal#Characters|Characters Journals]], a new tab will be available between the '''“Bio & Info”''' and '''“Attributes & Abilities”''' tab labelled '''“Character Sheet”'''. Much like the Attributes & Abilities tab, only players who have been granted Edit permissions for the journal entry will be able to access the Character Sheet tab.<br />
<br />
''See also:'' '''[[Add_character_sheet#Adding_New_Characters_In-Game|Create new character sheets to your players]]'''<br />
<br />
==Sheet Features==<br />
The '''D&D 5E by Roll20''' sheet has all of the functionality of a pen and paper character sheet, and much more. Certain aspects of the sheet have been streamlined or automated to remove bookkeeping and speed up gameplay. The key features are auto-calculations, [[Macro|macro]] buttons, and [[D&D 5e by Roll20 Roll Templates|roll templates]]. The sheet defaults to using the rules as printed in the D&D 5E SRD, however it's dynamic enough to allow you and your group to use many custom house rules you might want.<br />
<br />
===Auto Calculations===<br />
Many parts of the sheet use auto calculations to fill in derived attributes with the expectation that you're using the rules as printed in the 5th Edition SRD. Many of these calculated traits can be modified from the character sheet's <span style="font-family:Pictos;">y</span> [[D&D 5E by Roll20#Settings Page|Settings]]-tab, and those set by Sheet Workers can be edited directly. Below are some examples of Sheet Worker and Auto Calculation functionality:<br />
<br />
* '''Class''' - Changing the character's class from the header will automatically update the character's saving throw proficiencies, their hit die type, spell casting ability, and spell save DC. <br />
* '''Level''' - Changing the character's level will also update their proficiency bonus, number of spells per day, and more.<br />
* '''Attributes''' - Changing one of the character's attributes will also update the related modifier, skills that are based on that attribute, and derived stats such as initiative or passive perception.<br />
<br />
===Roll Buttons and Roll Templates===<br />
[[File:5E_OGL_Sheet_Rollable_Buttons.gif|right|frame|Any label that highlights in red when the mouse hovers over it is rollable.]]<br />
''Main Page:'' '''[[D&D 5e by Roll20 Roll Templates|D&D 5E by Roll20 Roll templates]]'''<br />
<br />
Most of the stats in the game can be rolled by hovering over their name, the stat will turn red, and then left-clicking the mouse. This is true for Attributes, Saves, Skills, Hit Dice, Death Saves, Tool Proficiencies, Attacks & Spellcasting, Spell Cards, and NPC Actions/Attacks. Any of these roll buttons can be dragged directly from the sheet to your [[Macro Quick Bar]], enabled from the <span style="font-family:Pictos;">y</span> [[My Settings]]-tab of Roll20's [[Sidebar]].<br />
<br />
Player characters have both a simple and attack [[D&D 5e by Roll20 Roll Templates|roll template]] that is output to the {{Text Chat}}-tab on the right hand [[Sidebar]]. The simple template is used for everything except for attacks. The attack template is shaped to show up in three pieces; the attack at the top, information in the middle, and damage at the bottom. Depending on your sheet settings, the damage will not roll automatically unless you click on the name of the attack from the roll template in the chat tab. This was designed to simulate the tabletop experience of rolling to attack and then rolling damage if necessary. You can change this behavior in the sheet <span style="font-family:Pictos;">y</span> [[D&D 5E by Roll20#Settings Page|Settings]]-tab, tab under "Auto Damage Roll".<br />
<br />
<div style="clear: both"></div><br />
<br />
====Rolling for Advantage and Disadvantage====<br />
With the '''D&D 5E by Roll20''' Sheet, the [[D&D 5E by Roll20#Settings Page|default sheet settings]] has Advantage set to ''always'' rolled for convenience purposes. It is commonly agreed upon that a gaming group uses the left roll result when advantage is not being used for a check. When advantage or disadvantage is in play, simply choose the higher or lower result among the two per usual. You can change this behavior in the sheet <span style="font-family:Pictos;">y</span> [[D&D 5E by Roll20#Settings Page|Settings]]-tab (gear icon at the top right of the page), tab under "Roll Queries". You have the choice of "Always Roll Advantage" (the default setting), "Advantage Toggle", "Query Advantage", or "Never Roll Advantage".<br />
<br />
'''Advantage Toggle:''' The Advantage Toggle will add three buttons to the top of your character sheet: "Advantage", "Normal", and "Disadvantage". You can click on any of these to roll for Advantage (the highest roll result will highlight in black), Disadvantage (the lowest roll result will highlight in black), or a single d20.<br />
<br />
'''Query Advantage:''' The Query Advantage setting will prompt a dialog box to appear whenever you roll from your sheet. It will ask you to select what sort of roll want to do (Normal, Advantage, Disadvantage). After choosing the type you want, the roll will occur in chat.<br />
<br />
'''Never Roll Advantage:''' When rolling from your sheet, only a single d20 will be rolled.<br />
<br />
===Resizable Text Fields===<br />
[[File:5E_OGL_Sheet_Resizable_Text_Fields.gif|right|frame|Making a text field larger is just a matter of click and dragging.]]There are many free-text fields on the sheet that give you a place to keep information that doesn't necessarily follow a specific format. All of the fields on the Bio Tab are free-text fields as well as the Description fields present for attacks, spells, equipment, features & traits, and NPC actions. If your text overflows past the bottom of a text field, you can resize it to view the content in its entirety by clicking and dragging the bottom right corner icon shown in the adjoining image.<br />
<br />
<br />
At present, these fields can only contain raw text. There are no formatting options (bold, italic, etc.) available.<br />
<br />
<div style="clear: both"></div><br />
<br />
===The Padlock Button and Organizing Elements===<br />
(aka. '''[[Character_Sheets#Repeating_Section|Repeating Section]]''')<br />
[[File:5E_OGL_Sheet_Padlock.gif|right|frame|The Padlock Toggle]]There is a <span style="font-family:Pictos;">(</span> (padlock) icon set at the bottom of several different fields of the '''D&D 5E by Roll20''' Sheet. It is used where a player is meant to add entries such as individual attacks, actions, pieces of equipment, features & traits, tool proficiences & custom skills, other proficiencies & languages, and spells. This icon behaves as a toggle button. <br />
<br />
When set in the <span style="font-family:Pictos;">(</span> locked position (default), a player can add new entries into the field. When the button is toggled to <span style="font-family:Pictos;">)</span>(unlocked), a player can no longer add new entries, but they will be able to reorder or delete any of the existing ones. The <span style="font-family:Pictos;">#</span>(red trash bin)-icon overlaid on the right hand side of the entry will delete it.<br />
<br />
{{Ambox<br />
|nocat=true<br />
| type = content<br />
| text = '''Deleting an entry cannot be undone!''' On left side of every entry while the padlock is <span style="font-family:Pictos;">)</span> unlocked is a re-sort icon symbolized by '''<big>≡</big>'''(three parallel lines). By clicking and dragging on this icon, you can rearrange the order of the entries in the field.<br />
}}<br />
<br />
{{Ambox<br />
|nocat=true<br />
| type = content<br />
| text = Some of the features of '''Repeating Sections''' do not work when the [[Character_Sheets#Character_Sheet_in_a_separate_window|Character Sheet is in a separate window]].<br />
}}<br />
<br />
<br />
<div style="clear: both"></div><br />
<br />
==Utilizing the 5th Edition SRD Compendium==<br />
[[File:5E_OGL_Sheet_Compendium.png|right|The Compendium Tab]]Upon adding the D&D 5E by Roll20 Character Sheet to a campaign, the [https://app.roll20.net/compendium/dnd5e/BookIndex| 5th Edition SRD Compendium] is automatically enabled for use from it's own <span style="font-family:Pictos;">i</span> [[Compendium]]-tab in the '''[[Sidebar]]''' of the application. It's located between the {{Journal}} and <span style="font-family:Pictos Custom;">u</span> [[Jukebox]]-tabs, and is accessible for both GM and Player alike.<br />
<br />
<br />
The <span style="font-family:Pictos;">i</span> [[Compendium]] allows for rapid searching of all rules, classes, monsters, spells, items, and more that are included in the 5th Edition SRD. This minimizes time spent for the gaming group to leaf through a book in the middle of a session for a rule clarification. Even better, both the GM and the Player can utilize dragging and dropping* from the <span style="font-family:Pictos;">i</span> [[Compendium]]-tab directly to your character sheets. This makes statting NPCs and PCs far faster than inputing everything manually.<br />
<br />
{{mbox | text = '''NOTE:''' The 5th Edition SRD is similar but NOT identical to the ''Dungeons and Dragons'' 5th Edition Rule Book. Some skills, classes, creatures, items, and other elements found within the ''Dungeons and Dragons'' rule book are strictly intellectual property of Wizards of the Coast and not accessible through their Open-Game License(OGL).}}<br />
<br />
<br />
===Statting PCs===<br />
Dragging from the <span style="font-family:Pictos;">i</span> [[Compendium]] works for the Equipment and Spell fields of the PC Sheet. This will not only carry over the name of the item or spell, but the relevant attack and damage rolls and any rules or flavor text that comes with it. Adding Compendium items in this fashion also automatically adds the equipment item (if it's a weapon) or spell to the Attacks & Spellcasting field to roll directly from. Items that modify a character's Attributes, Saves, AC, To Hit, Damage, Spell Attacks, and Spell DC will be automatically calculated on the sheet when dragged in. For example, if a Belt of Giant Strength is dragged to a sheet, the strength Attribute Score will become highlighted in blue and its attribute score will be increased. An asterisk is appended to the right of the score to also signify that it has been modified by an item. When you mouse over this number, the strength Attribute Score will revert back to what its unmodified total so you can refer back to it. Dropping a Compendium items that is an ammunition type (arrows, crossbow bolts, blowgun darts, etc) will automatically fill out a resource field for that item and link it to its entry in the Equipment section.<br />
<br />
To insert a Compendium item into the character sheet, run a search for the Item or Spell you want to add in the <span style="font-family:Pictos;">i</span> [[Compendium]]-tab. Once found, click and drag on the Compendium item's name so that it creates a little named tile that follows along with your mouse. Drag this over to the character sheet, it doesn't matter where. A text box that reads, "ACCEPTING DROP FROM COMPENDIUM" will appear on your sheet if this is done correctly. Let go of the tile and the entry will be auto-completed with all the data pertaining to the the Compendium entry in the correct location on the sheet. You can see this in action below under [[#Equipment|Equipment]].<br />
<br />
===Statting NPCs===<br />
You can fill out an entire NPC sheet in a single drag and drop. Run a search for the NPC you want to create from the <span style="font-family:Pictos;">i</span> [[Compendium]]-tab. Once found, click and drag on the NPC name so that it creates a little named tile that follows along with your mouse. Drag this to anywhere over the Tabletop area of the screen. Let go of the tile and a new character journal will be created named after the NPC from the Compendium entry. Its sheet will be changed over to the NPC sheet and filled with the entire NPC entry from the Compendium including their Actions, Reactions, and Legendary Actions if applicable. If you're using one of the Compendium expansions bought from the Roll20 Marketplace like the Monster Manual or Volo's Guide to Monsters, token art will also be pulled from the Compendium entry, placed on the table, and linked to your NPC's journal.<br />
<br />
You can also drag an NPC entry from the Compendium to an existing journal entry if you have the sheet open. If the sheet is in PC sheet mode, it will automatically change it over to the NPC sheet, and add its entry elements to it.<br />
<br />
One thing to note about dragging a stat block over from the Compendium is that it uses an ''additive'' behavior. It will not replace anything that you have already entered manually.<br />
<br />
=The PC Sheet=<br />
The '''D&D 5E by Roll20 Sheet''' contains both the PC Sheet ''and'' the NPC Sheet. By default, a new character journal is set to the PC sheet, but you can switch between the two by toggling it from the [[#Settings Page|General Options Settings]]. The PC Sheet is split up into four pages and can be selected from the buttons just underneath the header at the top of the sheet. They are listed from left to right order: The [[#Core Page|Core Page]], The [[#Bio Page|Bio Page]], The [[#Spells Page|Spells Page]], and The [[#Setting Page|Setting Page]].<br />
<br />
== Creating and Leveling up a character with Charactermancer ==<br />
Players and GMs using the '''D&D 5E by Roll20''' Sheet can use the Charactermancer to create and level up characters.<br />
<br />
'''How to use the Charactermancer for [[Charactermancer (D&D Fifth Edition)|character creation and leveling]].'''<br />
<br />
<br />
{{Ambox<br />
|nocat=true<br />
| type = content<br />
| text = The Charactermancer do not work when the [[Character_Sheets#Character_Sheet_in_a_separate_window|Character Sheet is in a separate window]].<br />
}}<br />
<br />
==Core Page==<br />
[[File:5E_OGL_PC_Core_Guide.jpg|right|frame|The Core Page]]The Core Page is selected by default and has most of the information you'll want to use on a regular basis to play your character. This should look very similar to the content you would normally find on the first sheet of the physical "D&D 5E by Roll20" player character sheet. The screenshot at the top of this wiki page displays the entirety of the Core Page. <br />
===(1) Core Header===<br />
[[File:D&D5E-Roll20-core-header.png|550px]]<br />
<br />
The header block at the top of the sheet changes based on the page you have selected. On the Core page you can select a class by its dropdown menu. The available options from the dropdown are: Barbarian, Bard, Cleric, Druid, Fighter, Monk, Paladin, Ranger, Rogue, Sorcerer, Warlock, and Wizard. You can create a custom class from the Settings Page.<br />
<br />
Once a class has been selected you can update the class's level by changing the number next to the class. The sheet will also automatically mark the abilities that class has proficiency in as well as automatically select the dice that will be used when Hit Dice are rolled. You can change the Hit Dice setting manually from the options menu. If your character multi-classes, then the secondary class and its level will appear beside the primary class. This Class and Level field can hold up to four classes if desired.<br />
<br />
The fields for Background, Race, Alignment, and Experience Points allow you to fill in whatever text you wish to put in them. The Character Name persists over all pages of the sheet and is tied to the name you give to the journal entry. Changing it on the sheet itself will also change the name on the character journal and vice versa once it is closed.<br />
<br />
===(2) Attributes===<br />
<br />
[[File:5E_OGL_Sheet_Attribute_Block.jpg|left]]Along the left side of the sheet are listed the 6 primary attributes: Strength, Dexterity, Constitution, Intelligence, Wisdom, and Charisma. These attributes are used by almost every other calculation on the sheet, as they are the core definition of a character. Each attribute block has the core attribute score, which can be changed by modifying the number in the oval at the bottom of each block, and, inside the square, the attribute modifier which is auto-calculated based on the score below it. All racial ability score increases must be manually added to the core attribute score using the settings "gear" symbol at the top of the page (where the Core, Bio, and Spells buttons are located.) The attribute modifier uses the following calculation to set the value:<br />
<br />
<br />
<code>[[floor((@{strength}-10)/2)]]</code><br />
<br />
The attribute can be referenced by its name, such as @{dexterity} while the attributes modifier can be referenced by adding the mod suffix, @{dexterity_mod}.<br />
<br />
<div style="clear: both"></div><br />
<br />
===(3) Inspiration===<br />
<br />
[[File:D&D5E-Roll20-inspiration.png|left]]You can track whether or not you have Inspiration by clicking the circle next to the Inspiration block at the top left of the Core page. This will toggle a dragon spiral icon on and off for indication purposes.<br />
<br />
<div style="clear: both"></div><br />
<br />
===(4) Proficiency Bonus===<br />
<br />
[[File:5E_OGL_Sheet_Proficiency.png|left]]Your character's proficiency bonus is listed near the top left of the page. You cannot modify this value manually, instead it is automatically set based off your character's over-all level. Your character's Level can be set by changing the number next to your Class name in the [[#header_info|Header]] at the top when on the Core page.<br />
<br />
<div style="clear: both"></div><br />
<br />
===(5) Saving Throws===<br />
<br />
[[File:5E_OGL_Sheet_Saving_Throws.png|left]]Next to the core Attributes on the left side of the page is a list of the same attributes to be used in making saving throws. To mark an attribute that your character has proficiency in for saving throws, check the box next to the appropriate attributes. When you select a class in the header section of the Core page it will automatically check the correct boxes for that class's proficiencies.<br />
<br />
You can add an additional field to Saving Throws to serve as a Global Save Modifier. An example is if the character is under the influence of the Bless spell and can roll a 1d4 in addition to the result of their saving throws. This is enabled from the Settings Page under General Options. Once enabled a seventh checkbox and field will be added at the bottom of the Saving Throws block with a text field to enter the additional die roll. For this example, you could enter "1d4[BLESS]" in the global checkbox's text field that you can enable when the character is under the effects of the Bless spell. The word between the brackets becomes a label that can be seen when you mouse over the roll result in chat. While this Global Save Modifier is checked, every roll made from the Saving Throws block and performing a Death Save will add this modifier to the result.<br />
<br />
<div style="clear: both"></div><br />
<br />
===(6) Skills===<br />
[[File:5E_OGL_Sheet_Skills.png|left]]<br />
To the right of the Core Attributes is a list of all of the character's Skills. Each skill can be rolled by clicking on the skill name. If you have proficiency in a specific skill, then you would check the box next to the skill name, this will automatically add your proficiency bonus to that skill's checks. Each skill also lists the core attribute, that is used in the roll calculations, next to it in parenthesis.<br />
<br />
You can set advanced skill options for the Settings page, such as skill expertise, flat bonuses from class archetypes or feats, as well as Jack of All Trades.<br />
<br />
<div style="clear: both"></div><br />
<br />
===(7) Armor Class, Initiative, & Speed===<br />
<br />
[[File:D&D5E-Roll20-AC-Init-Speed.png|left]]The Armor Class & Speed blocks at the top center of the page can be used to keep track of your Armor and Speed values. The Initiative block cannot be modified manually, but instead is auto-calculated based off your character's Dexterity. If you have any additional initiative modifiers you can add them on the {{gear}} [[#Settings Page|Settings Page]] under Initiative Modifier in the Class Options block.<br />
<br />
Armor Class can also be tracked automatically by using the [https://app.roll20.net/compendium/dnd5e/BookIndex Compendium] compatible inventory, on by default.<br />
<br />
You can configure a custom AC calculation using the {{gear}} [[#Settings Page|Settings Page]] under the Attribute Tracking section. It's listed as "Armor Class Tracking" and is set to "Automatic" by default. If you select Custom, you can select up to two different attributes to apply to the character's armor class.<br />
<div style="clear: both"></div><br />
<br />
====Using the Global AC Modifiers====<br />
If you check the "Show Global AC Modifier" field in the character sheet General Options settings, the sheet will display a repeating section to configure and apply different modifiers to AC. So, for example, if your character has a common bonus, such as from a spell or a conditional feat or fighting style, you can toggle that AC bonus from the character sheet directly.<br />
<br />
====Rolling for Initiative and the Turn Order Tracker====<br />
Clicking on the word INITIATIVE will roll that character's initiative score. If your players have [[Token|tokens]] linked to their character sheets, they can roll their initiative ''and'' simultaneously add their character and its initiative score to the {{Turn Tracker}} automatically. What is required of the player is that their linked token must be currently selected on the Tabletop before they roll off their sheet.<br />
<br />
If you would like to enable a tie breaker component to Initiative, there is an option to enable this from the [[#Settings Page|Settings Page]] under the "Attribute Options" block. What this does is that it will add your dexterity Attribute Score as a decimal value to your Initiative. So if you have a character with a dexterity attribute score of 14, your initiative modifier will change from a <code>2</code> to a <code>2.14</code>.<br />
<br />
===(8) Hit Points & Temporary Hit Points===<br />
[[File:5E_OGL_Sheet_HP.png|left]]The Current Hit Points and Temporary Hit Points blocks are used to keep track of your character's Hit Points (HP). Inside the Current Hit Points block, at the top, is a line that lists the character's maximum amount of HP. <br />
<br />
<br />
When your character takes damage, if they have any, it should be subtracted from their Temporary Hit Points first, then any remaining damage would then come off of the character's Current Hit Points.<br />
<br />
<div style="clear: both"></div><br />
<br />
===(9) Hit Dice===<br />
[[File:5E_OGL_Sheet_Hit_Dice2.png|left]] The Hit Dice block is used to keep track of and roll your character's hit dice. Inside the Hit Dice block, at the top, is a line to keep track of the total number of dice your character can have. In the main area of the block you would keep track of the remaining hit dice. Clicking the "HIT DICE" label will roll the hit dice for your selected class automatically. If you wish to change the dice that is rolled you can do so in the Class Options section of the [[#Settings Page|Settings Page]] ({{gear}} icon). <br />
<br />
<br />
If your character is multi-classed, when rolling your hit dice (by clicking "''HIT DICE''", a pop-up will ask which of your character's current class's hit dice you want to roll. This input accepts only numerals a input to make automatic tracking of the [[API:A Guide to the API|API]] possible.<br />
<div style="clear: both"></div><br />
<br />
===(10) Death Saves===<br />
[[File:5E_OGL_Sheet_Death_Saves.png|left]]The Death Saves block is used to keep track of your character's death save rolls once they have been knocked out. You can click the "DEATH SAVES" label to make a death save roll. If you roll greater than 10 you would check one of the boxes next to "Successes" otherwise you would check a box next to "Failures". If your character has any modifiers to their death save rolls they can be added in the Class Options section of the Settings Page(gear icon).<br />
<div style="clear: both"></div><br />
<br />
===(11) Attacks & Spellcasting===<br />
[[File:5E_OGL_Sheet_Attacks_And_Spellcasting.png|left]]The Attacks & Spellcasting block in the center of the Core page of this character sheet will be one of the most often used sections. To start, you can manually add any attack or spell to this section by hovering over the block and clicking the "Add" button(the <span style="font-family:Pictos;">&</span> symbol). This will open a form that can be filled out with all of the information about the specific attack or spell you are adding. <br />
<br />
<br />
This section will automatically add attacks, with all the stats, for spells that have an attack component when they are added to your spell sheet on the [[#Spells Page|Spells Page]]. This happen both if you add the spell manually or if you drag and drop a spell from the <span style="font-family:Pictos;">i</span> [[Compendium]]. An attack is also automatically created if you drag and drop an item from the Compendium into your sheet.<br />
<br />
<div style="clear: both"></div><br />
[[File:Poisoned Dagger 5e Attack.png|right|frame|An example of an attack form filled out for a physical attack using a +1 Poisoned Dagger]]For example, lets say Erin the Bold has a +1 Poisoned Dagger that has the stats of a regular dagger, but also metes out an additional 1d6 of poison damage alongside the typical 1d4 points of piercing damage. The image displayed to the right is how the attack would be set up:<br />
<br />
<br />
Since this is a [https://app.roll20.net/compendium/dnd5e/Items:Dagger#h-Dagger dagger], and daggers have the "[https://app.roll20.net/compendium/dnd5e/Weapons#h-Weapons Finesse]" attribute I can chose either STR or DEX for my bonus attribute. Erin is quicker than she is strong, so we will pick DEX as the attribute to attack with, as well as checking the "proficient" checkbox since Erin is experienced with using these sorts of weapons. She doesn't have any other gear that might make her attacks better, so we will leave the generic bonus between the attribute and proficiency blank, or 0. Being a +1 Poisoned Dagger means that it is also magical, so it gets a 1 in the magic bonus slot just below. A dagger can also be used as a thrown weapon, so we've added the weapon's throwing range info to the "Range" field. Since a weapon does damage, we have checked the first "Damage" checkbox and filled in the required fields. This dagger does 1d4 piercing damage + Erin's DEX mod + 0 bonus damage (this would be used for bonus damage on top of the magical +1) and it doesn't have anything to change the critical damage so we just put the same damage into the "crit" box. Because this dagger can also cause poison damage, we also check the second "Damage" checkbox and fill in the info for the 2nd set of damage. The poison does a flat 1d6 poison with no extra bonuses, so we've selected "-" to say there is no attribute that adds to this damage. This damage also doesn't have anything to make the crit different so we set that to 1d6 as well. There are no extra saving throws or effects that are included with this attack, so we leave these additional sections blank. <br />
<br />
These additional effect sections will be used more commonly with spells, like [https://app.roll20.net/compendium/dnd5e/Fireball#h-Fireball Fireball], where you would require a DEX save against your SPELL DC, which will be set according to your character's spell casting level. For a fireball, the save effect would be "half damage" and the "Description" would be something like "Hits all creatures within 20 ft of the explosion point".<br />
<br />
After you are done modifying all of individual stats for an attack you can click the gear icon at the top right of that section and it will hide the stats for that attack. If ever you need to change these stats in the future you can hover over the entry and click the <span style="font-family:Pictos;">y</span>(gear)-icon that shows up to unhide the stats section. <br />
<br />
<div style="clear: both"></div><br />
====Adding Global Attack and Damage Modifier====<br />
You can add two special entries to the Attacks & Spellcasting block to handle to global Attacks and Damage modifications to rolls. An example is if the character is under the influence of the Bless spell and can roll a 1d4 in addition to the result of their attack roll. This is enabled from the [[#Settings Page|Settings Page]] under General Options. Once enabled, a checkbox will be added at the bottom of the Attacks & Spellcasting block with a text field to enter the additional die roll. For this example, you could enter <nowiki>"1d4[BLESS]"</nowiki> in the global checkbox's text field that you can enable when the character is under the effects of the Bless spell. The word between the brackets becomes a label that can be seen when you mouse over the roll result in chat. While these Global Modifiers are checked, every roll made from the Attacks & Spellcasting block will add these modifiers to the result.<br />
<br />
====Rolling from the Attacks & Spellcasting Block====<br />
[[File:Poisoned Dagger 5e Roll.png|frame|An attack roll from a +1 Poisoned Dagger]]Rolling from the Attacks & Spellcasting Block is no different than rolling from any other portions of the character sheet. Hovering your mouse over any entry here will highlight its entire label (NAME, ATK, and DAMAGE/TYPE) in red and you'll be able to click on it to roll the attack or spell. You can also drag this entry into the Macro Bar to give yourself easy access to this attack. Because this is a repeating section, the macro name will be a bit messy, but you can right-click the button and rename the macro to whatever you like.<br />
<br />
With any attack that checks for AC, you will see TWO rolls set side by side for the Armor Class check with the name of the attack listed underneath them with the Attack modifier bonus (ATK) appended to the Attack name in light grey. The Roll20 D&D 5E Character Sheet ''always'' rolls for Advantage by default, so you will always have two roll results for this check (most gaming groups use the left roll result if neither Advantage or Disadvantage is being factored in the check). If there is a specified range for the attack, this will be listed above the attack's name.<br />
<br />
Underneath the AC Check and Attack Name is the Damage roll result for the attack. Underneath this roll result will be the Damage Type (ex. slashing, piercing, poison, fire, etc.) listed in light grey italicized font.<br />
<br />
For spells that don't check for AC and instead require a Saving Throws to mitigate or negate the spell's effect, the SPELL DC is listed first. Underneath this, in italicized font, is the effect if a character succeeds the check listed. Underneath the effect is the required attribute saving throw that must be rolled. If Damage is applied, this result is rolled and listed next with its Damage Type.<br />
<br />
[[File:5e_attack_example.gif|right|frame|How to view attack damage when the sheet is set to "Don't Auto Roll Damage"]]<br /><br />
<br />
<br />
{{mbox | text = '''NOTE:''' If your character sheet's Settings have "Auto Damage Roll" set to "Don't Auto Roll Damage" under General Options, the damage will not be listed underneath the AC roll result in chat. The damage was rolled, but presently hidden from view. Anyone can see the damage delivered by manually unfolding the roll result open by hovering your mouse over the roll result in chat and clicking on the attack/spell's name.}}<br />
<div style="clear: both"></div><br />
<br />
===(12) Personality Traits, Ideals, Bonds, and Flaws===<br />
These text fields lock to prevent accidental edits. When a sheet is first created, these fields are unlocked and given a dashed yellow border to the top of the field to showcase that they're editable. To lock the field after entering text, click on the gear icon in the upper right corner of the field. This will remove the yellow border and the field will conform in height to display everything within it.<br />
<br />
There presently isn't a means to format the raw text (italicize, bold, font alignment, etc) within these fields and any line breaks are stripped out. If you ever need to edit the content again while the field is locked, mouse over the desired field and the gear icon will reappear in the top right. Clicking on that will unlock the field once again for edits.<br />
<br />
===(13) Class & Other Resources===<br />
[[File:5E_OGL_Sheet_Resources.png]]<br />
<br />
The Class & Other Resource Blocks can be used to keep track of either an item quantity you have in your equipment (like arrows in a quiver), or skills that don't fit into the other sections on the sheet (like a '''Sorcerer's Sorcery Points''', a '''Cleric's Channel Divinity''' at higher levels, or the number of rounds a '''Barbarian''' has been '''Raging''' so far in a combat encounter).<br />
<br />
There are 3 fields per Block:<br />
* Resource Max:<br />
** The Resource Max field is a text box which allows you to quantify exactly what you're tracking (ex. "Total: 10 Rounds").<br />
* Resource:<br />
** The Resource field is a numeral that you dial up or down or input directly.<br />
* Resource Name:<br />
** The Resource Name is a text box that allows you to label the resource when you click on the light grey "OTHER RESOURCE" label to overwrite it with your own.<br />
**"OTHER RESOURCE" is placeholder text<br />
<br />
<br />
A resource block will be filled automatically if you checkmark an Equipment item as "USE AS A RESOURCE" & the Item Quantity field will be paired with the Resource field in the Resource block & vice versa (you'll need to click outside of the field or hit Enter for changes to refresh across the sheet). If the two resource blocks given by default are not enough then you can add additional blocks by hovering over the section & clicking the "Add" (+ symbol) button.<br />
<br />
The Item Name will also be added to the Resource Name field, however the Resource Max field is apparently not linked to the Item currently.<br />
<br />
If you drag & drop an ammunition item type from the Compendium into your character sheet, the item is added to the Equipment block & is automatically listed & linked as an Other Resource.<br />
<div style="clear: both"></div><br />
To call the first set of class resources use:<br />
* Class Resource <code>@{class_resource}</code><br />
* Other Resource <code>@{other_resource}</code><br />
<br />
<br />
To call the Repeating resources use<br />
* Repeating Resource 1st left<code>@{repeating_resource_$0_resource_left}</code><br />
* Repeating Resource 1st right<code>@{repeating_resource_$0_resource_right}</code><br />
* Repeating Resource 2nd left<code>@{repeating_resource_$1_resource_left}</code><br />
* Repeating Resource 2nd right<code>@{repeating_resource_$1_resource_right}</code><br />
* etc.<br />
<br />
<br />
If you want to do a basic Full Readout of the Repeating Resource, the Format would be (Top Left to Bottom Right):<br />
* Class: <code>@{class_resource_name}: @{class_resource} / @{class_resource|max}</code><br />
* Other: <code>@{other_resource_name}: @{other_resource} / @{other_resource|max}</code><br />
* Left 0: <code>@{repeating_resource_$0_resource_left_name}: @{repeating_resource_$0_resource_left} / @{repeating_resource_$0_resource_left|max}</code><br />
* Right 0: <code>@{repeating_resource_$0_resource_right_name}: @{repeating_resource_$0_resource_right} / @{repeating_resource_$0_resource_right|max}</code><br />
* Left 1: <code>@{repeating_resource_$1_resource_left_name}: @{repeating_resource_$1_resource_left} / @{repeating_resource_$1_resource_left|max}</code><br />
* Right 1: <code>@{repeating_resource_$1_resource_right_name}: @{repeating_resource_$1_resource_right} / @{repeating_resource_$1_resource_right|max}</code><br />
* etc.<br />
<br />
===(14) Tool Proficiencies===<br />
[[File:5E_OGL_Sheet_Tool_Proficiencies.png|left]]The Tool Proficiencies block is for listing a character's Tool Proficiency skills. At the bottom of this block is an "Add" (<span style="font-family:Pictos;">&</span> symbol) button. Clicking this will add a new entry to this block where you can add all of the relative stats for a specific tool proficiency, say Woodcarver's Tools. You can set the level of proficiency to either Proficient, Expertise, or Jack of All Trades. The roll bonus for that tool will reflect the proficiency level selected. Next is an Attribute drop down menu where you can select which character attribute to roll with for a proficiency check. One of the options you can choose is "QUERY ATTRIBUTE" which when you click on the Tool Proficiency to roll it, you will be prompted to choose which attribute you would like to use. The attribute used for the check will be up to the GM when it is time to make the roll check. If there is any additional bonus modifiers that come along with the tool in question, you can input it in the "MODS:" field.<br />
<br />
Once you finished filling out the stats for this tool you can click the <span style="font-family:Pictos;">y</span>(gear) icon at the top right of the entry to hide the stat fields and leaving behind just the rollable button. You can roll by either clicking on this rollable button or dragging it to your [[Macro Bar]].<br />
<br />
You can also use this section to create custom skills or rolls for your campaign setting or home-brew ruleset. Check out the [[#Custom Skills and Stats|Advanced Use]] section for further details.<br />
<br />
====Global Skill Modifier====<br />
You can add a special entry to the Tool Proficiencies & Custom Skills block to handle to global Attacks and Damage modifications to rolls. An example is if the character is under the influence of the Guidance spell and can roll a 1d4 in addition to the result of their skill check. This feature is enabled from the [[#Settings Page|Settings Page]] under General Options. Once enabled, a checkbox will be added at the bottom of the Tool Proficiences & Custom Skills block with a text field to enter the additional die roll.<br />
<br />
For this example, you could enter "1d4[Guidance]" in the global checkbox's text field that you can enable when the character is under the effects of the Guidance spell. The word between the brackets becomes a label that can be seen when you mouse over the roll result in chat. While this Global Modifier is checked, every roll made from the Tool Proficiencies & Custom Skills block and the Skills block will add this modifier to the result.<br />
<div style="clear: both"></div><br />
<br />
===(15) Other Proficiencies & Languages===<br />
[[File:5E OGL Sheet Proficiencies.png|left]]<br />
This block can be set up to be Compendium Compatible (where you can add repeating sections for individual items) or as one resizable free-text field to enter whatever you wish in here. If you don't feel the Tool Proficiency block is needed (as in, you don't feel like your party will ever have to roll individual tool sets), you can store a character's Tool Proficiencies here instead. There presently isn't a means to format the raw text (italicize, bold, font alignment, etc). You can adjust this block's behavior by going to the Settings Page of the sheet and going to the General Options block to change whether this block uses the Simple or Compendium Compatible layout.<br />
<br />
When the Other Proficiences & Languages block is made Compendium Compatible, each repeating field lists a Type selection field and a Proficiency text field. Type has the following options available from its drop down selection menu: Language, Weapon, Armor, Other. <br />
<p style="clear:both;"></p><br />
<br />
===(16) Equipment===<br />
[[File:5E OGL Sheet Equipment.png|framed|right|The Equipment block of the PC Sheet]]<br />
The Equipment block at the bottom of the page has 2 different versions: a Simple version that features a single plain text field where you can track all of your equipment in any format you wish and a Compendium Compatible version that allows you to drag and drop items from the Compendium to automatically populate repeated sections for each indivdual piece of equipment.<br />
<br />
To swap between the two different Equipment block versions, first, go to the sheet's Settings Page (gear icon at the top right of the page) and then to the "General Options" section. Here, on the field labeled "Inventory", you can select between "Simple" or "Compendium Compatible" respectively. Like the name implies, if you want to be able to copy items directly from the Compendium using drag and drop, you must use the Compendium Compatible version. Dragging item entries from the Compendium to the character sheet will add it fully filled in the Equipment section as well as other automated actions described below.<br />
<br />
====Automated Compendium Functionality====<br />
If you populate the Equipment block by dragging and dropping <span style="font-family:Pictos;">i</span> [[Compendium]] items, there are several automatic features that occur when the entries you drag in our equipment items.<br />
Auto-Equip: Every item dragged to the sheet is automatically equipped in the Equipment Section<br />
*'''Weapons:''' A weapon dragged in from the Compendium will add an attack in the Attacks and Spellcasting section for that item.<br />
*'''Armor:''' Armor that is dragged in from the Compendium will add its bonus to the Armor Class (while equipped) section. If you drag multiple pieces of armor to the same sheet and at least two armor entries are equipped at once, a warning will pop up in red at the top of the Equipment Block that the Armor Class isn't being correctly calculated because of the bonus overlap. This warning will dissapear when you unequip down to a single set of armor.<br />
*'''Magical/Wondrous Items:''' Items that modify Attributes, Saves, AC, To Hit, Damage, Spell Attacks, and Spell DC will add that bonus to those elements on the sheet. In most cases, the attribute that is being modified will highlight in blue and followed with an asterisk to showcase that the attribute is being modified by an item. Mousing over the modified number will display the base value of that attribute before the item's modification is applied. This stat modification only applies if the item is equipped in the Equipment section and it will remove its bonus if it is unequipped.<br />
*'''Ammunition:''' Items dragged in from the Compendium that are used for ammunition such as arrows, bolts, darts, and slingstones, will automatically populate and link to an Other Resource field.<br />
<br />
====Manually Adding Items====<br />
You can also add items manually by hovering over the block and clicking the "Add" button (+ symbol). Each equipment entry, by default, show fields for quantity, name, and weight of an item. If you hover over a row and click the small "information" icon (grey-filled circle with a lowercase i centered in it) that appears at the bottom right of the entry you can also set some additional features. <br />
<br />
*'''Equipped Checkbox:''' The checkbox changes the appearance of the Item Name so it's easier to tell what your character currently has equipped from a glance. When left unchecked, the Item Name's font turns grey. When checked, the Item Name becomes a solid black.<br />
*Use As A Resource Checkbox: When checked, this will enable one of the Class Resource blocks and list the item name and its quantity within it. The quantity is tied between the two so changing it in one will be reflected in the other field after clicking outside the field.<br />
*'''PROP:''' This is a text field where you would take note of weapon properties such as ''finesse'', ''versatile'', or ''light''.<br />
*'''MODS:''' This is a text field where you would take note if an item (likely magical) would modify your stats in some fashion such as a character's Attributes, Saves, Skills, AC, To Hit, Damage, Spell Attacks, and Spell DC. If a stat is modified here, its attribute value will become highlighted in blue and adjusted by the supplied modifier listed here. An asterisk is appended to the right of the value to also signify that it has been modified by an item. While your mouse is hovering over the attribute, it will revert back to its unmodified total so you can refer back to its pre-moddified value.<br />
**The format for a stat modification is ''stat name:n'' where n is the stat bonus (ex. ''Strength:21'')<br />
*'''Description Field:''' This is a simple text field to include a description of the particular item and of any special qualities or effects it might have on the player.<br />
Some if not all of these fields will be filled in automatically when adding from the Compendium (where applicable).<br />
<br />
Both versions of the equipment field have the sections for each of the [https://app.roll20.net/compendium/dnd5e/Treasure#h-Treasure coins] you may find on your adventures: copper(CP), silver(SP), electrum(EP), gold(GP), and platinum(PP).<br />
<br />
====Encumbrance====<br />
If you are following Encumbrance rules, the <span style="font-family:Pictos;">i</span> [[Compendium|Compendium Compatible]] Equipment block will automatically calculate and track the weight of your character's backpack if you enter the weight values for any of the items in your Equipment list. When your character becomes encumbered, and depending on its severity, the words ENCUMBERED, HEAVILY ENCUMBERED, or IMMOBILE will display in red underneath the TOTAL WEIGHT value. You can also choose to follow Simple, Variant Encumbrance rules, or not follow Encumbrance rules at all by toggling it off on the [[D&D 5E by Roll20#Settings Page|Settings Page]] under "General Options".<br />
<br />
====Mods====<br />
The Mods field of each piece of equipment can modify the values of ability scores, AC, saving throws, Skill (Ability) checks and more. What follows is a list of the modifiers, and the proper syntax for adding them.<br />
<br />
All modifiers are separated by commas. There are other modifiers that can appear the mod field, used in creating the item from a compendium drag and drop operation, but the modifiers below have live effects on the character sheet, depending on if the item is marked as “equipped”.<br />
<br />
'''replace the <code>+n</code>, with the number you want.''' For example, if you want to boost Animal Handling skill by 3, you look at the table and find <code>Animal Handling +n</code>, so you will add to your item <code>Animal Handling +3</code>.<br />
<br />
{| class="wikitable" <br />
|-<br />
! Modifier<br /><br />
! Effect<br /><br />
|-<br />
| style="width: 20%;" | '''Combat Modifiers'''<br />
| '''These affect items that provide attacks (Appear in the attack section of the character sheet)'''<br />
|-<br />
| Melee Attacks +n<br />
| Adds +n hit "Magic Bonus" to that attack. It is not global, and only affects a weapon(melee or ranged), not an item, staff or other category. The bonus is figured into the attacks display on the 5e sheet.<br />It is NOT ''Melee Attack''.<br />
|-<br />
| Melee Damage +n<br />
| Adds +n damage "Magic Bonus" to that attack. It is not global, and only affects a weapon(melee or ranged), not an item, staff or other category. The bonus is listed separately in the attacks display on the 5e sheet.<br />
|-<br />
| Spell Attack +n<br />
| Adds a global +n to the character's Spell Attack bonus.<br />It is NOT ''Spell Attacks.''<br />
|-<br />
| '''Saving Throws'''<br />
| '''All modifiers stack with “Saving Throws +n'''<br />
|-<br />
| Strength Save +n,<br />Dexterity Save +n,<br />Constitution Save +n,<br />Intelligence Save +n,<br />Wisdom Save +n,<br />Charisma Save +n<br />
| Adds a +n to the indicated saving throw<br />''Do not use a colon.''<br />
|-<br />
| Saving Throws +n<br />
| Adds a Global Modifier to ALL saving throws.<br />
|-<br />
| Spell DC +n<br />
| Adds a global +n to a spell casting character’s Spell Save DC.<br />It is NOT Spell ''Save'' DC.<br />
|-<br />
| '''Ability Scores'''<br />
| <br />
|-<br />
| Strength +n,<br />Dexterity +n,<br />Constitution +n,<br />Intelligence +n,<br />Wisdom +n,<br />Charisma +n<br />
| Provides a bonus to the indicated ability score, which will appear in blue on the sheet while the bonus is active.<br />Do not use a colon. ''Strength: +10'' will do nothing<br />
|-<br />
| Strength n,<br />Dexterity n,<br />Constitution n,<br />Intelligence n,<br />Wisdom n,<br />Charisma n<br />
| Replaces the indicated ability score, which will appear in blue on the sheet while the bonus is active.<br />Do not use a colon. ''Strength: 10'' will do nothing<br />
|-<br />
| '''Skills'''<br />
| <br />
|-<br />
| Acrobatics +n,<br />Animal Handling +n,<br />Arcana +n,<br />Athletics +n,<br />Deception +n,<br />History +n,<br />Insight +n,<br />Intimidation +n,<br />Investigation +n,<br />Medicine +n,<br />Nature +n,<br />Perception +n,<br />Performance +n,<br />Persuasion +n,<br />Religion +n,<br />Sleight of Hand +n,<br />Stealth +n,<br />Survival +n<br />
| Adds the value to the indicated Skill roll. Note that in this case, the <code>+</code> and a colon are optional. <code>Acrobatics +5</code>, <code>Acrobatics 5</code>, <code>Acrobatics: +5</code>, <code>Acrobatics: 5</code> will all add <code>5</code> to the character’s Skill roll. For consistency and to guard against future functionality, it’s probably best to follow the format for ability scores, and use a plus sign with no comma: <code>Acrobatics +5</code>.<br />There is no Global Skill modifier<br />
|-<br />
| '''AC'''<br />
| <br />
|-<br />
| AC +n<br />
| By itself, <code>AC: 13</code> adds 13 to the character’s Armor Class. It does not replace it. <br /><br />If <code>Shield</code>, <code>Light Armor</code>, <code>Medium Armor</code>, or <code>Heavy Armor</code> is also in the mods field, it will change the calculation.<br />''<code>Light Armor, AC: 13</code>'' will give a formula of 13 + dex mod<br />''<code>Medium Armor, AC: 13</code>'' will give a formula of 13 + dex mod (max +2)<br />''<code>Heavy Armor, AC: 13</code>'' will give you flat AC 13<br />''Shield, AC: 13'' would add 13 to the your AC. The Shield keyword is superfluous in this case.<br />''<code>Shield, AC: 2</code>'' will just add 2 to the AC.<br />Finally, a bare modifier, such as for a Ring of Protection can just be written as <code>AC: +2</code> or <code>AC +1</code>.<br /><br />Shield or bare AC bonuses will stack with other armor mods on different items. You cannot equip multiple armors simultaneously, or have a custom armor equation on the settings tab and wear an armor. This will generate a flag.<br /><br />The + and a colon are semi-optional. <code>AC +5</code>, <code>AC: +5</code>, <code>AC: 5</code> will all work. However, <code>AC 5</code> will do nothing. For consistency and to guard against future functionality, it’s probably best to indicate a base AC as <code>AC: n</code> and a Shield as <code>AC +n</code>.<br />At this point, there is no way to differentiate between Ranged AC and Melee AC, though some magic items such as the ''Arrow Catching Shield'' make the distinction.<br />
|}<br />
<br />
<br />
<br />
<div style="clear: both"></div><br />
<br />
===(17) Features & Traits===<br />
[[File:5E OGL Sheet Features Traits.png|thumbnail|left|The Compendium Compatible itemized version of the Features & Traits section]]<br />
The '''Features and Traits '''-block is the place to store '''Class-''', '''Race-''' and '''Background Features''', '''Feats''', and other special notes about your character or of a certain piece of equipment or ability. When using the Charactermancer, the previously mentioned features appears in this section.<br />
<br />
This block can be set up to be <span style="font-family:Pictos;">i</span> [[Compendium|Compendium Compatible]] (where you can add repeating sections for individual items) or as one resizable free-text field to enter whatever you wish in here. You can adjust this block's behavior by going to the [[D&D 5E by Roll20#Settings Page|Settings Page]] of the sheet and going to the '''General Options'''-block to change whether this block uses the Simple or Compendium Compatible layout. <br />
<br />
When adding items to the Compendium Compatible version of this block, you have the <code>Name</code> field, a <code>Source</code>-field where you can choose between (Racial, Class, Feat, Background, or Other) , a <code>Source Type</code>-text field to describe the type, and then the multilined <code>Description</code>-textbox. Clicking on the <span style="font-family:Pictos;">y</span>(gear)-icon in the top right corner of the item will lock/unlock the item's editability. When locked down, a <span style="font-family:Pictos;">w</span>(chat bubble)-icon appears when you mouse over the feature/trait. Clicking on the <span style="font-family:Pictos;">w</span> will share this feature's description in the {{Text Chat}}.<br />
<br />
There presently isn't a means to format the raw text (italicize, bold, font alignment, etc) of the Simple version or in the Description section of either version of the Features & Traits block.<br />
<br />
You can drag-n-drop '''Feats''' from the compendium, even though they can't be selected in the Charactermancer on levelup.<br />
<br />
PC Features and Traits can be called using an ability roll:<br />
<code>%{selected|repeating_traits_$0_output}</code><br />
Simply increase the $0 value to access all Features and Traits listed on the character sheet, $1, $2, $3...<br />
<br />
<p style="clear:both;"></p><br />
<br />
==Bio Page==<br />
[[File:D&D5E-Roll20-BIO-tab.png|right|thumb|250px|The Bio Page of the PC Sheet]]The Bio page, opened by selecting "BIO" from the 4 buttons near the top right of the sheet, is comprised of free-form text fields that can be used to keep track of less "structured" information about your character. You can use this page to describe your character's appearance, keep track of who their allies are and what organizations they've worked for, and on this page is a section to supplement the inventory list, on the front page, with the "Treasure" section, where you can keep track of all the loot you find along your travels.<br />
===Bio Header===<br />
[[File:D&D5E-Roll20-Bio-header.png|550px]]<br /><br />
<br />
The header of the Bio page contains the basic run down of a character's physical appearance.<br />
*'''Character Name:''' This is carried over from every single PC Page and matches the character journal's name<br />
*'''Age:''' The character's current age<br />
*'''Size:''' The size classification for the race type (Medium for most cases)<br />
*'''Height:''' The character's height<br />
*'''Weight:''' The character's weight<br />
*'''Eyes:''' The character's eye color<br />
*'''Skin:''' The character's skin color<br />
*'''Hair:''' The character's hair color/style<br />
<br />
===Character Appearance===<br />
While the Bio Header describes the bare bone physical characteristics of a PC, this field is for fleshing out the visual peculiarities and/or cues of your character. Does you character have a piercing gaze? A stooped posture? Are they fancily dressed or are their clothes moth-eaten? In essence, this field is for everything and anything one would note about the character–from the equipment or garb they wear to how they comport themself.<br />
<br />
===Allies & Organization===<br />
This text field is for listing important or campaign relevant NPCs that the character may have a connection with. It's also for keeping track of faction allegiance. In the case of ''Dungeons & Dragons''' Forgotten Realms world, a PC could be a member of the Harpers or the Emerald Enclave, among other major factions who are all vying for power of the continent.<br />
<br />
===Character Backstory===<br />
This field is for listing your character's pre-campaign history, their relations, and the pertinent places they have been to in the past.<br />
<br />
===Additional Features & Traits===<br />
This text field is a continuation of the [[#.2817.29_Features_.26_Traits | Features & Traits]] section of the Core Page. The section on the Core Page is a good place for commonly utilized features of a character or briefly jotting down an abbreviated list. This field on the Bio page gives you more real estate to fully write down everything you need in whole.<br />
<br />
===Treasure===<br />
This text field is where you can list all the loot you've collected while searching bodies and delving through dungeons. Since much of these effects are transient and are likely to be used, given away, or sold to the highest bidder at the earliest opportunity, this may be preferable place to keep this list of items rather than adding them to the itemized Compendium Compatible Equipment section (if you have that version enabled).<br />
<br />
==Spell Page==<br />
[[File:D&D5E-Roll20-Spells-tab.png|right|thumb|400px|The Spell Page]]The Spell page, opened by selecting the "SPELLS" button from the four buttons near the top right of the sheet, is used to keep track of all of the powerful magics at your character's fingertips.<br />
<br />
===Spell Page Header===<br />
[[File:D&D5E-Roll20-Spells-header.png|550px]]On the Spells page Header you can set the ability modifier that will be used for casting spells. Selecting the Spellcasting Ability block will allow you to select an attribute from a dropdown, and this will be used in all relevant spell rolls. This attribute will be set automatically when you select a spell casting class. The next two blocks, the Save DC and Attack Bonus will be set automatically based on the class that is selected on the Core page.<br />
<br />
===Spellcasting Ability===<br />
The Spellcasting Ability modifier will automatically update, depending on the class you select on the Core page, to the correct ability modifier for your class. If, for some reason, you need to change this value you can click on the modifier listed in this section and it will give you a drop-down list of all available ability modifiers.<br />
<br />
===Spell Save DC & Attack===<br />
The Spell Save DC and Spell Attack Bonus sections cannot be changed manually, but are just a visual output of modifiers that will be happening behind the scenes. The Spell Attack Bonus is the number that will be added to all spell attack rolls, automatically.<br />
<br />
The Spell Save DC refers to the Save DC that enemies will have to beat when they are trying to dodge/resist your incoming spells. Say, Fred the Sorcerer casts Lightning bolt, and his Spell Save DC is 14. Any enemies hit by his attack will have to make a DEX save and try to beat 14. If they manage to beat the attack, then they are only grazed and take half of the damage. If they don't beat 14, then they take the full damage of the attack instead.<br />
<br />
===Spell Levels & Spells Per Day===<br />
The main section of the Spells page lists 10 sections, ranging from 0 to 9, representing the Cantrips (0) and spells level 1 - 9 where the level of the spell is listed in the triangle on the left of each section header. The number in the left square of the header represents the total number of Spell Slots, in other words, the maximum number of times a spell of this level can be cast in between long rests. This number will be set automatically depending on the level of your character, but can be modified by clicking the up or down arrow or just entering a number in the space provided. The number in the right-most box in the headers is the Slots Remaining value that can be used for you to keep track of the number of times you've cast a spell at this level.<br />
<br />
===Adding Spells===<br />
[[File:D&D5E-Roll20-Spells-Icons.png|framed|right]]<br />
When you drag spells from the <span style="font-family:Pictos;">i</span> [[Compendium]] to the sheet, a new spell entry will be added to the Spell Page under the appropriate level header. This will copy over all corresponding information linked to the spell, as well as creating an attack entry in the [[D%26D_5E_by_Roll20#.2811.29_Attacks_.26_Spellcasting|Attacks & Spellcasting]]-block on the "Core" page, if the spell can be used as an attack. The name of the spell will be listed to the left of the entry and to the right are icons for whether the spell is a Ritual (R), requires Concentration (C), and lists whether there is a Verbal (V), Somatic (S), or Material (M). There is also a circle at the far left of the entry that can be toggled to be filled in with red or left empty. This toggle represents spells that are Prepared for the day and are available for a player's convenience to help track this.<br />
<br />
You can manually add spells by selecting the <span style="font-family:Pictos;">&</span> under any of the Spell Level headings. This will present you with a blank template where you can enter all of the information about a spell. By default, the spell card only contains non-attack information about a spell. If the spell IS an attack you can change the "Output" selector from "Spellcard" to "Attack", this will show some additional input fields to fill out the attack information about the spell. Switching this input will also add an attack entry to the [[D%26D_5E_by_Roll20#.2811.29_Attacks_.26_Spellcasting|Attacks & Spellcasting]]-section on the [[#Core Page|Core page]] so this spell attack can also be cast from the main page. All of these sections are linked, so changing information in one place will also change the corresponding information in the other location. To save your edits, click on the gear icon at the upper right of the entry to collapse the spell entry.<br />
<br />
You can edit any spell at any time, by hovering your mouse over the entry to make a <span style="font-family:Pictos;">y</span> icon appear on the left. Clicking on the <span style="font-family:Pictos;">y</span> will roll out the spell once more to be edited.<br />
<br />
==Settings Page==<br />
[[File:D&D5E-by-Roll20-Settings-Page.png|thumb|right|400px|The Settings tab of the sheet, accessed from the '''<span style="font-family:Pictos;">y</span>''' icon ]]<br />
The Settings page, accessed by selecting the <span style="font-family:Pictos;">y</span>(gear) icon from the four buttons near the top right of the sheet, is where you can make changes to some parts of your character sheet that aren't represented on the other pages.<br />
<br />
===Class Options===<br />
In the class options section is where you have access to some important parts of your character, that usually are managed in the background. They are placed here so that, if needed they can be modified as well.<br />
<br />
'''Hit Dice:''' This section will be set automatically depending on the class chosen on the [[#Core Page|Core page]], but can be changed here by selecting the value and choosing a new one from the drop-down menu. This option is used whenever the "Hit Dice" section is used on the Core page.<br />
<br />
'''Carrying Capacity Modifier:''' This modifier allows you to increase the weight that a character can carry before they become encumbered.<br />
<br />
'''Global Magic Attack Modifier:''' This modifier will affect all spell attacks rolled from the sheet.<br />
<br />
'''Magic Caster Level:''' By default, a character's caster level is tethered to their class level. This option allows you to set the caster level manually, so you can have it differ from the character's class level. This will automatically change the Spell Slots Total for each spell level on the [[#Spell Page|Spells page]].<br />
<br />
'''Spell Save DC Mod:''' The Spell Save DC is normally a field you can't edit from the Spell page and is set by the character's class and level. This modifier allows you to alter that value.<br />
<br />
'''Spell Icons:''' This option will allow you to choose to turn off all the Spell Icons (R, C, V, S, & M), show them all, or only display only the ritual and concentration icons.<br />
<br />
'''Halfling Luck:''' Use this checkbox if your character is a Halfling that happens to take advantage of the Halfling Luck race feat. Using this feat will automatically re-roll any 1s rolled for attacks and skills or ability checks/saves.<br />
<br />
'''Arcane Fighter/Rogue:''' These checkboxes can be used to keep track of when your Fighter or Rogue-classed character actually has access to spells.<br />
<br />
===Multiclass Options===<br />
If you are taking advantage of the D&D 5E multiclassing you can keep track of it in this section. Any levels to your character's additional classes must be changed here, and will then be reflected in the header portion of the sheet. Once you've added additional classes in this section, any time you roll Hit Dice from the Core page it will ask you which classes hit dice you wish to use.<br />
<br />
Note: Be sure to not re-include your main class in this section, or your final level calculation will be incorrect.<br />
<br />
===Custom Class Options===<br />
If you are playing a class that is not part of the D&D 5E Compendium, you can input the important class information in this section, and checking the "Use Custom Class" checkbox will replace the main class selection with your custom built class.<br />
<br />
===Spell Slot Modifiers===<br />
This section allows you to manually modify how many spell slots your character has available for each spell level from 1 to 9.<br />
<br />
===Attribute Options===<br />
'''Attribute Modifiers:''' With this section you can manually adjust the individual Attribute Scores for Strength, Dexterity, Constitution, Intelligence, Wisdom, and Charisma.<br />
<br />
'''Initiative Modifier:''' Usually, your initiative modifier is just based off of your DEX modifier, but if you happen to find a magical item that enhances these rolls this is where you will put that bonus. This modifier will be used whenever the [[#.287.29_Armor_Class.2C_Initiative.2C_.26_Speed|Initiative]]-section is rolled on the Core page.<br />
<br />
'''Initiative Style:''' This setting allows you to select whether Initiative will be rolled with Advantage, Disadvantage, or rolled normally with a single d20 (default).<br />
<br />
'''Add DEX Tiebreaker to Initiative:''' If you would like to enable a tie breaker component to Initiative, this checkbox will enable adding your dexterity Attribute Score as a decimal value to your Initiative roll. So if you have a character with a dexterity attribute score of 14, your initiative modifier will change from a 2 to a 2.14.'<br />
<br />
'''Global Armor Class Modifier:''' This setting will modify your armor class and will be taken into account regardless of the equipment the character uses.<br />
<br />
'''Armor Class Tracking:''' There are three options available: The Automatic version that's default to the sheet where it adds 10 + your DEX modifer and then takes any armor equipped into account. A Custom version which expands out a formula upon selection where you can input your own formula for armor tracking, or you can turn Off Armor Tracking entirely. When turned off, you will need to manually adjust the Armor Class field on the Core page.<br />
<br />
===Save Options===<br />
'''Save Modifiers:''' With this section you can manually adjust the individual Save modifiers for Strength, Dexterity, Constitution, Intelligence, Wisdom, and Charisma.<br />
<br />
'''Death Save Modifier:''' A normal death save is usually just a D20 against a dc of 10, but if you're lucky enough to have a bonus to death saves, this is where you will put your bonuses. This modifier will be represented any time a "Death Save" is rolled from the Core page.<br />
<br />
'''Global Saving Throw Modifier:''' If you have an affect that would modify all saving throws, this option makes it easier to adjust your Save modifiers than having to go in and change each one individually. This modifier will be used every time any save is rolled from the sheet.<br />
<br />
===Skill Options===<br />
If your class offers the ability to achieve "Expertise" in a skill, or if you are using a Bard with the "Jack of All Trades" feat, this is where you will make these adjustments. There is also a section to add flat modifiers to any of your skills if your character has an archetype ability like Remarkable Athlete or a feat that adds a flat bonus to a skill. You can add expertise to any skill by clicking the value next to it and choosing "Expertise" from the drop-down menu. If your Bard has the Jack of All Trades feat, you can check the checkbox at the bottom of this section and it will automatically give half of your character's proficiency points to any skill check that doesn't have full proficiency.<br />
<br />
'''Passive Perception Modifier:''' This option will add a bonus to a character's Passive Perception which is not something you can change directly from the Core page of the sheet.<br />
<br />
===General Options===<br />
The General Options section has some important options that deal more with how the sheet works, rather than actual character creation. Most importantly, the NPC checkbox at the top, which will change the sheet to be the NPC version which is shaped to more easily track an NPC's information.<br />
<br />
'''Roll Queries - Always/Toggle/Query/Never Roll Advantage:''' This option will change how advantage is rolled for all attacks. It defaults to always roll advantage, which means that every time an attack is rolled it will roll twice and present the outcome of both rolls. This is useful for both advantage and disadvantage, otherwise you can just choose either the left or the right to be the default roll. Toggle adds a set of buttons at the top of the sheet to manually switch your advantage options between rolls. If Query is chosen, every time a roll is made it will ask you whether or not it's advantage. If Never is chosen, then it will always roll just a single dice per attack roll.<br />
<br />
'''Whisper Rolls to GM:''' Like above, you have the option to Never/Toggle/Query/Always whisper rolls to the GM. When this option is enabled, the attack roll will only be whispered to the GM and not made public.<br />
<br />
'''Auto Damage Roll:''' By default, damage rolls will not be rolled automatically, but only when you click the attack in the chat window. This is useful because you can choose to only roll damage when an attack hits. Using this option you can make the character always roll damage with every attack.<br />
<br />
'''Core Die Roll:''' You can change the core die (by default it is 1d20) to something else entirely here.<br />
<br />
'''Proficiency Bonus:''' By default, the character's Proficiency Bonus is calculated by class level. This setting allows you choose to calculate this bonus via By Level (the default), via a Proficiency Die as described in the Dungeon Master's Guide, or a Custom calculation which rolls out a field to enter a roll formula for the bonus.<br />
<br />
'''Global Save/Skill/Attack/Damage Modifier Field:''' This series of checkboxes will add new entries to the Saving Throws, Tools Proficiencies & Custom Skills, and Attacks & Spellcasting blocks respectively to add global modifiers (like if a character is under the effects of a Bless or Guidance spell). Each entry will have a Global label in grey at the bottom of its entry and a field to enter the modifier bonus. If you include a word in brackets with the bonus formula (ex. "1d4[Bless]"), the word enclosed in the brackets will appear when you mouse over a roll to see it's formula.<br />
<br />
'''Add Character Name to Templates:''' This option allows you to turn this on or off. When it is on, the character's name is listed in the roll template when rolls are made from the sheet. If the character sheet in question is for an NPC, you will likely want to have this off so the rolls don't accidentally show your hand of what sort of monster your party is facing. This setting is off by default.<br />
<br />
'''Auto Level Calculations:''' This option allows you to turn this on or off. When it is on, adjusting the character's class level will automatically update the character's proficiency bonus, Hit Dice, and spell Slot totals (if the class is a spellcaster).<br />
<br />
'''Encumbrance:''' This option dictates how encumbrance is handled on the Equipment block of the Core page. This requires your Inventory to be set to "Compendium Compatible" to automatically calculate and track the weight of your character's backpack if you enter the weight values for any of the items in your Equipment list. When your character becomes encumbered, and depending on its severity, the words ENCUMBERED, HEAVILY ENCUMBERED, or IMMOBILE will display in red underneath the TOTAL WEIGHT value. This setting has three options: Simple Encumbrance Rules, Variant Encumbrance Rules, or not follow Encumbrance rules at all by toggling it off from this.<br />
<br />
'''Inventory:''' With this option allows you to either have your Equipment block be "Compendium Compatible" or "Simple". The Simple version of the Equipment block will give you single text field to log your inventory. The Compendium Compatible version tracks weight, quantity, and attack options in an itemized list for every equipment item you add to the block.<br />
<br />
'''Features & Traits:''' This option can set the Features & Traits block to be either a single text field or a repeated section that will be Compendium Compatible to list traits and features in an itemized list.<br />
<br />
'''Proficiencies & Languages:''' This option can set the Proficiences & Languages block to be either a single text field or a repeated section that will be Compendium Compatible to list traits and features in an itemized list.<br />
<br />
'''Ammo Tracking (API Required):''' When using the 5th Edition OGL Companion API Script in your game (Pro Subscriber feature), you can set attacks to weapons using ammunition to automatically subtract from their tally in their Resource block. So if your character is equipped with a bow, rolling its attack will automatically remove an arrow from its Resource block.<br />
<br />
===Transition Options(outdated)===<br />
{{mbox | text = This feature doesn't seem to exist on the sheet any longer, so the info in this section is outdated}}<br />
<br />
If your campaign previously used the [https://wiki.roll20.net/DnD5e_Character_Sheet#Intro Community Contributed] or [https://wiki.roll20.net/index.php?title=DnD5e_Shaped_Character_Sheet&oldid=11112#General_Information Shaped Legacy] 5th Edition Character Sheets and you are swapping over to this one, we have an automated conversion tool that will clear or merge elements left over from those two sheets. This procedure can only be done ''once'' and can not be undone. It is recommended that you make a copy of your campaign first before attempting a sheet transition.<br />
<br />
There is also a checkbox that hides this feature entirely from the sheet. If you hide this by mistake, you can gain access to it again by creating a new character journal.<br />
<br />
=The NPC Sheet=<br />
''See Also:'' '''[[D&D5E by Roll20 NPC Attributes]]'''<br />
<br />
One of the most useful parts of the D&D 5E by Roll20 Character Sheet is that it contains both a PC sheet ''AND'' an NPC sheet. An NPC doesn't normally require the depth a PC sheet needs, so the NPC sheet is a much more slimmed down character sheet that doesn't require multiple pages like its PC counterpart. You can access this version of the sheet by going to the Settings Page, by clicking the gear icon near the top right of the sheet, and then checking the NPC checkbox. This will switch the sheet to the NPC version. You can switch back at any time by unchecking the NPC option under General Options on the new page.<br />
<br />
==NPC Options==<br />
[[File:5E_OGL_Sheet_NPC_Options.png|right|thumb|250px|The NPC Options Section]]This is the area where all of the NPC's stats will be entered, it covers everything from the NPC's name, to how strong or quick or smart it is, to what languages it speaks. Most of the fields in this section are just text fields used to keep track of information about the NPC. All of the information entered in these fields will be visible in the stat block once the NPC options are hidden. <br />
<br />
<br />
Any text that appears in light grey is placeholder text. It's there to offer you an example of what the content would be for any given field. <br />
<br />
By default, no skill or ability checks will show up in the NPC's stat block. Once you've added a value to the corresponding skill or ability save, they will appear. If for some reason the NPC will have to make a check with a skill or ability it does not have any bonus in, you can enter a 0 as the modifier for that check and it will add it to the list in the stat block below.<br />
<br />
The XP of an NPC auto-calculates based on its given challenge rating.<br />
<br />
If the NPC is a spellcaster, you can check the checkbox beside '''SPELLCASTING NPC''' and this will add a spell list section that utilizes the spell list and its functionality from the PC version of the sheet.<br />
<br />
At default, you can add Traits and Actions in their respective places after the Challenge Rating and XP area of the Stat Block. For Reactions and Legendary Actions, you need to enable them from the NPC Options section. For Reactions, check off the '''HAS REACTIONS''' checkbox. This will add a new sections to the Stat Block for you to add Reactions to. If an NPC is a monster with Legendary Actions then you must enter the number of actions that monster has access to each turn in the '''LEGENDARY ACTIONS:''' field. Once you add a number here, an additional section will appear in the stat block below, where you can add the specific legendary actions that the monster is able to do.<br />
<br />
The NPC sheet supports Compendium drag & drop. If you want to add a new monster to your game just drag the monster from the <span style="font-family:Pictos;">i</span> [[Compendium]]-tab of the [[Sidebar]] and drop it to anywhere on the Tabletop. This will automatically create a new journal entry named the same as the Compendium entry and will copy all of the information on that compendium page directly into the new sheet. If you have purchased any of the Compendium expansions that expands on the available NPCs like the Monster Manual or Volo's Guide to Monster, a token of that NPC will be added to the Tabletop that will have its stats automatically set and linked to the new journal entry.<br />
<br />
{{mbox | text = '''Note:''' If you already have a journal entry in your {{journal}}-tab with the exact same name as the <span style="font-family:Pictos;">i</span> [[Compendium]] entry, the drag and drop will not work as this automation will stop to prevent overwriting existing content the user has already created. If a drag and drop of an NPC Compendium page does not create a journal entry, run a search for that NPC's name in your Journal to see if an entry already exists. If you do not want to delete the older entry, renaming it will allow the drag and drop to work as expected.}}<br />
<br />
===General Options===<br />
Within the NPC Options section, directly below the Legendary Actions field, is the General Options that are featured on the PC Sheet: NPC checkbox, WHISPER ROLLS TO GM, and the AUTO DAMAGE ROLL options. <br />
<br />
*NPC checkbox<br />
*WHISPER ROLLS TO GM<br />
*AUTO DAMAGE ROLL<br />
*NPC NAME IN ROLLS<br />
*ADD DEX TO TIEBREAKER TO INITIATIVE<br />
<br />
Unchecking the NPC checkbox from here will revert the sheet back to the PC Sheet.<br />
<br />
===Hiding NPC Options===<br />
Once all of the desired information has been entered, you can click the <span style="font-family:Pictos;">y</span>(gear) icon at the top right to hide this section. This leaves behind just the NPC's stat block where you can make all of your rolls from. You can re-open this section to edit the information at any time by clicking on the <span style="font-family:Pictos;">y</span> icon again. It's in the same location regardless if you're looking at NPC Options or the NPC stat block.<br />
<br />
==The NPC Stat Block==<br />
[[File:5E OGL Sheet NPC v2.png|right|thumb|250px|An NPC stat block for a griffon]]Following NPC Options is the NPC Stat Block that is built off of what you input in the NPC Options section. This area may look very similar to a stat block you may find in a monster bestiary or published adventure.<br />
<br />
<br />
Any section of the stat block that has a corresponding roll will have click-able text. For example, if the NPC has to make a CON check, you can click the CON attribute to roll a CON check with all of the required modifiers automatically included. If you added a value to one of the skill modifier fields then that skill will show up in the NPC's "Saving Throws" list where you can click it to make a saving throw roll using that skill's modifier.<br />
<br />
The first section of the Stat Block mirrors all the information you added in the NPC Options section. This content is meant exclusively for rolling and can not be edited directly. You will need to change them from the NPC Options section.<br />
<br />
===Traits===<br />
Traits are pieces of information about an NPC that isn't covered by the NPC options section. These are entered directly onto the NPC's stat block. If you click the "<span style="font-family:Pictos;">&</span>" button that appears right below the "Senses/Languages/Challenge Rating" section it will add a blank entry where you can add a single trait for that NPC. Each Trait Entry features a bold title field which is then followed by a larger text box for the description of the trait. You can add any number of Traits for any NPC.<br />
<br />
===Actions===<br />
NPC actions can be used for any number of things. Each entry initially offers an Action Name field as well as a large text field for the Action description. The checkbox for ATTACK, once checked, adds more structured data fields needed for an attack roll (Type, Range/Reach, To Hit bonus, Target, Damage Roll, and Damage Type). To add a new entry you will select the <span style="font-family:Pictos;">&</span> button that appears below the Actions section. Once all of this is complete you can click the <span style="font-family:Pictos;">y</span>(gear) icon at the top of this entry to hide the input fields, leaving just the action text. You can show this information, or roll the attack, in the chat box by clicking the text for the action. If you need to make further modifications to any action you can hover over the row you wish to edit, then click on the <span style="font-family:Pictos;">y</span>(gear) icon again. This will show all of the action information input fields again. You can add any number of Actions for any NPC.<br />
<br />
===Bonus Actions===<br />
NPC bonus actions are typically not listed on the sheet, and are usually referenced in the Traits section. However, if a player wishes to use this section, it is available if the 'Bonus Action' checkbox is selected. The fields work the same as the Actions section.<br />
<br />
===Reactions===<br />
Once enabled from the NPC Options section, a new heading labeled "Reactions" and its relevant section is added to the stat block that allows you to add Reactions. These entries operate just like Traits.<br />
<br />
===Spells===<br />
Once enabled from the NPC Options section, a new heading labeled "Spells" and its relevant section is added to the stat block that allows you to add Spells. These entries will operate identically to how Spells are added and handled on the PC Sheet with the one noted exception that there is only a single column of spell entries. You can drag spells from the Compendium to add spell entries just like you would with the PC's Spell sheet. Any and all spells added to the character sheet are shared between the NPC and the PC versions.<br />
<br />
===Legendary Actions===<br />
If a number value is added to the LEGENDARY ACTIONS field in the NPC Options section, the Legendary Actions heading and section is added at the very bottom of the stat block and lists some verbiage on how many actions are available to be used on a given turn. This number is dictated by what you entered in the NPC Options. These entries operate the same way as Traits.<br />
<br />
==Rolling for Initiative for NPCs==<br />
There are two ways to roll for Initiative on the NPC sheet. You can click on the NPC's Name to roll for Initiative or you can roll from the die icon labeled INIT that is listed to the right of the Armor Class and Hit Points section of the NPC sheet, towards the top. If you have the Turn Tracker tool open, having the NPC token selected while rolling Initiative will automatically add the NPC and its initiative roll to the tracker. Creatures on the GM layer that are added to the tracker in this fashion will have their entries hidden from the players.<br />
<br />
<br />
You can also create a global Macro that will pop up as a Token Action button in the upper left hand corner of the tabletop every time a token is selected. This will allow you to roll without looking at the NPC sheet at all. The macro formula should look just like this:<br />
<br />
<code>%{selected|npc_init}</code><br />
<br />
=Advanced Use=<br />
<br />
===Custom Skills and Stats===<br />
You can set up any number of custom skills or rolls from the [[#Tool Proficiencies|Tool Proficiencies]] section just underneath the skill section on the Core tab. [[#Class & Other Resources|The Resources]] section is also useful for tracking custom stats to your campaign, game setting, or home-brew rules. There are also various options available from the Settings page to modify attributes, skills, saves, spells, and more.<br />
<br />
===Target Roll Buttons===<br />
A useful way for GMs and Players to reference their abilities is by dynamically setting up a handful of macros that can be used on a token linked to a character, rather than having to roll directly from the sheet. To do this, you'll set up a global macro from the {{Collections}}-tab. You can also write these directly in the {{Text Chat}}.<br />
<br />
In the examples, the <code>selected</code> part can be replaced with <code>target</code>, a character's name, or it's character ID.<br />
<br />
Here are some examples:<br />
<br />
'''PC'''<br />
* Attributes: <code>%{selected|strength}</code>, <code>%{selected|strength_save}</code> | Will roll the Strength Check and Strength Save for the selected [[token]](if the [[Link Token|token is linked to a sheet]])<br />
* <code>%{selected|acrobatics}</code><br />
* <code>%{selected|initiative}</code><br />
* <code>%{selected|death_save}</code><br />
* <code>%{selected|hit_dice}</code><br />
<br />
'''NPC'''<br />
* <code>%{selected|npc_init}</code><br />
* <code>%{selected|npc_str}</code><br />
* <code>%{selected|npc_stealth}</code><br />
* <code>%{selected|npc_hpformula}</code><br />
====Rolling from Repeating Sections====<br />
The example we'll be using today is setting up the 1st NPC action:<br />
<code>%{selected|repeating_npcaction_$0_npc_action}</code><br />
Now whenever you use this macro it will roll the first NPC action of whichever NPC token you have selected. You can set up a roll for each action by incrementing the 0 by 1 for each action you wish to add (I.E. <code>$1</code>, <code>$2</code>, <code>$3</code>). Here is a list of important repeating section rolls and their formulas:<br />
<br />
* Player Attack/Spell Attack <code>%{selected|repeating_attack_$0_attack}</code><br />
* Player Attack/Spell Damage <code>%{selected|repeating_attack_$0_attack_dmg}</code><br />
* Player Attack/Spell Critical Damage <code>%{selected|repeating_attack_$0_attack_crit}</code><br />
* Player Global DMG mod <code>%{selected|repeating_damagemod_$0_global_save}</code><br />
** Attr names: <code>global_damage_name</code>, <code>global_damage_damage</code>, <code>global_damage_critical_damage</code>, <code>global_damage_type</code><br />
* Proficiencies <code>%{selected|repeating_proficiencies_$0_output}</code><br />
* Tool/Custom Skill <code>%{selected|repeating_tool_$0_tool}</code><br />
* Traits/Feats: <code>%{selected|repeating_traits_$0_output}</code><br />
<br />
* Spellbook Cantrip <code>%{selected|repeating_spell-cantrip_$0_spell}</code><br />
* Spellbook Level 1 <code>%{selected|repeating_spell-1_$0_spell}</code><br />
* Spellbook Level 2 <code>%{selected|repeating_spell-2_$0_spell}</code><br />
* Spellbook Level 3 <code>%{selected|repeating_spell-3_$0_spell}</code><br />
* Spellbook Level 4 <code>%{selected|repeating_spell-4_$0_spell}</code><br />
* Spellbook Level 5 <code>%{selected|repeating_spell-5_$0_spell}</code><br />
* Spellbook Level 6 <code>%{selected|repeating_spell-6_$0_spell}</code><br />
* Spellbook Level 7 <code>%{selected|repeating_spell-7_$0_spell}</code><br />
* Spellbook Level 8 <code>%{selected|repeating_spell-8_$0_spell}</code><br />
* Spellbook Level 9 <code>%{selected|repeating_spell-9_$0_spell}</code><br />
<br />
'''NPC'''<br />
* NPC Traits/Abilities<code>%{selected|repeating_npctraits_$0_npc_roll_output}</code><br />
* NPC Actions/Attacks<code>%{selected|repeating_npcaction_$0_npc_action}</code><br />
* NPC Attack Damage<code>%{selected|repeating_npcaction_$0_npc_dmg}</code><br />
* NPC Attack Critical Damage<code>%{selected|repeating_npcaction_$0_npc_crit}</code><br />
* NPC Bonus Actions<code>%{selected|repeating_npcbonusaction_$0_npc_action}</code><br />
* NPC Legendary Actions<code>%{selected|repeating_npcaction-l_$0_npc_action}</code><br />
* NPC Mythic Actions<code>%{selected|repeating_npcaction-m_$0_npc_action}</code><br />
* NPC Spells<code>%{selected|repeating_spell-npc_$0_spell}</code><br />
<br />
===Directly Referencing Attributes===<br />
You can discover the name of most of the attributes in the sheet by hovering over them. After a couple of seconds a title will pop up and tell you how to referencing them. You can call attributes in an Ability Rolls by using <code>@{attributename}</code>. If you want to directly reference it in a roll that isn't saved on the sheet, you need to specify the character's name, or use either the <code>selected</code> or <code>target</code> key works.<br />
<br />
'''Examples:'''<br />
* <code>/em attempts to grapple and gets [[1d20+@{strength_mod}]]</code> custom [[Journal#Attributes_.26_Abilities_Tab|Ability call]], saved in the "attributes and abilities" tab of the character sheet.<br />
* <code>/r 1d20+@{Alice|strength_mod}+@{Alice|pb}</code> macro that calls a specific character<br />
* <code>/em have @{selected|hp} out of @{selected|hp|max} left.</code> macro that uses stats from a token(token must be selected before rolling)<br />
* <code>The Enemy's AC is @{target|npc_ac}</code> macro prompt the user to select a target token on the map, and uses it's stats.<br />
<br><br />
<br />
See [[Macros#Attribute_Macros]] for further general details/examples on the syntax.<br />
====PC====<br />
Here are a list of some of the more important stats:<br /><br />
<br />
'''Attributes/Saves'''<br />
<br />
* Str: <code>strength, strength_mod, strength_save_bonus</code><br /><br />
* Dex: <code>dexterity, dexterity_mod, dexterity_save_bonus</code><br /><br />
* Con: <code>constitution, constitution_mod, constitution_save_bonus</code><br /><br />
* Int: <code>intelligence, intelligence_mod, intelligence_save_bonus</code><br /><br />
* Wis: <code>wisdom, wisdom_mod, wisdom_save_bonus</code><br /><br />
* Cha: <code>charisma, charisma_mod, charisma_save_bonus</code><br />
<br><br />
'''Skills'''<br />
<br />
<code>athletics_bonus<br /><br />
acrobatics_bonus<br /><br />
animal_handling_bonus<br /><br />
arcana_bonus<br /><br />
deception_bonus<br /><br />
history_bonus<br /><br />
insight_bonus<br /><br />
intimidation_bonus<br /><br />
investigation_bonus<br /><br />
medicine_bonus<br /><br />
nature_bonus<br /><br />
perception_bonus, passive_wisdom<br /><br />
performance_bonus<br /><br />
persuasion_bonus<br /><br />
religion_bonus<br /><br />
sleight_of_hand_bonus<br /><br />
stealth_bonus<br /><br />
survival_bonus<br /><br />
</code><br />
<br />
'''AC, Proficiency, HD etc'''<br />
<br />
<code>pb</code>(Proficiency Bonus)<br><br />
<code>inspiration</code><br><br />
<code>ac<br /><br />
initiative_bonus<br /><br />
speed<br /><br />
hp, hp|max, hp_temp<br /><br />
hit_dice, hit_dice|max, hitdietype<br /><br />
weighttotal<br /><br />
</code><br />
<br />
'''Spells in general'''<br><br />
<br />
These are individual variables that you can access, that contain information on a character's spellcasting capabilities in general.<br><br />
<br />
<code>spell_save_dc, spell_attack_bonus</code><br><br />
<code>lvl1_slots_total, lvl1_slots_expended</code><br><br />
<code>lvl2_slots_total, lvl2_slots_expended</code><br><br />
<code>lvl3_slots_total, lvl3_slots_expended</code><br><br />
<code>lvl4_slots_total, lvl4_slots_expended</code><br><br />
<code>lvl5_slots_total, lvl5_slots_expended</code><br><br />
<code>lvl6_slots_total, lvl6_slots_expended</code><br><br />
<code>lvl7_slots_total, lvl7_slots_expended</code><br><br />
<code>lvl8_slots_total, lvl8_slots_expended</code><br><br />
<code>lvl9_slots_total, lvl9_slots_expended</code><br><br />
<br />
<br />
'''Spells, repeating sections'''<br><br />
<br />
These are sections, which means that each of them contains several variables that you can access. For example, "repeating_spell-1" is a section that contains all the variables that relate to a character's 1st-level spells.<br><br />
<br />
<code>repeating_spell-cantrip</code><br><br />
<code>repeating_spell-1</code><br><br />
<code>repeating_spell-2</code><br><br />
<code>repeating_spell-3</code><br><br />
<code>repeating_spell-4</code><br><br />
<code>repeating_spell-5</code><br><br />
<code>repeating_spell-6</code><br><br />
<code>repeating_spell-7</code><br><br />
<code>repeating_spell-8</code><br><br />
<code>repeating_spell-9</code><br> <br />
<br />
'''Spells, the variables within those repeating sections'''<br><br />
<br />
Building on our previous example from the sections, if you start with "repeating_spell-1", and then add "_$0" to the end of it, then now you're referring to the topmost spell in your list of 1st-level spells. And, if you then add an attribute name (see the list of attribute names here below), then you can narrow your reference even further. For example, if you use "repeating_spell-1_$0_spellname", then you are referring to the name of the aforementioned spell. And if you add "_spellrange" instead of "_spellname", then you are now referring to the range of the aforementioned spell.<br><br />
<br />
'''List of attribute names, for spells'''<br><br />
<br />
<code>spellname</code><br><br />
<code>spellrange, spellcastingtime, spelltarget, spellduration</code><br><br />
<code>spellschool</code><br><br />
<code>spellritual</code><br><br />
<code>spellconcentration</code><br><br />
<code>spellcomp_v, spellcomp_s, spellcomp_m</code><br><br />
<code>spellcomp_materials</code><br><br />
<code>spell_ability</code><br><br />
<code>spelloutput</code><br><br />
<code>spellattack</code><br><br />
<code>spelldamage</code><br><br />
<code>spelldamagetype</code><br><br />
<code>spelldamage2</code><br><br />
<code>spelldamagetype2</code><br><br />
<code>spellhealing</code><br><br />
<code>spelldmgmod, spell_damage_progression</code><br><br />
<code>spellsave, spellsavesuccess</code><br><br />
<code>spelldescription</code><br><br />
<code>spellclass, spellsource</code><br><br />
<br />
'''Items'''<br><br />
<code>cp sp ep gp pp</code><br><br />
(copper pieces, silver, gold, electrum, platinum)<br />
<br />
<code>repeating_inventory_$#_itemcount<br><br />
repeating_inventory_$#_itemname<br><br />
repeating_inventory_$#_itemweight<br><br />
repeating_inventory_$#_equipped<br><br />
repeating_inventory_$#_useasresource<br><br />
repeating_inventory_$#_hasattack<br><br />
repeating_inventory_$#_itemproperties<br><br />
repeating_inventory_$#_itemmodifiers<br><br />
repeating_inventory_$#_itemcontent</code><br><br />
<br />
* <code>equipped</code>, <code>useasresource</code>, <code>hasattack</code> are checkboxes, with value 1 if checked.<br />
* <code>itemmodifiers</code> is for of item changes any stats, like <code>AC +2</code> adding +2 to AC when equpped.<br />
* <code>itemcontent</code> is the item description<br />
<br><br />
'''The class_resource and the other_resource'''<br><br />
<br />
The resources <code>class_resource</code> and <code>other_resource</code> are static resources. That is to say, you need to keep in mind that they are NOT a part of the repeating section, even though it definitely looks that way on the character sheet.<br><br />
<br />
You use these to access them<br />
<br />
<code>class_resource</code><br><br />
<code>class_resource_max</code><br><br />
<code>class_resource_name</code><br><br />
<code>other_resource</code><br><br />
<code>other_resource_max</code><br><br />
<code>other_resource_name</code><br><br />
<br />
'''The repeating resources'''<br><br />
<br />
Any resources that appear beneath the "class resource" and the "other resource" are a part of the "repeating resources" section. This section is known for being confusing for beginners, so it deserves a bit of clarification.<br />
<br />
First, keep in mind that this is one section (not two sections, as people often think), and that "repeating_resource" is its section prefix.<br />
<br />
Second, keep in mind that you need to skip past the row with the "class resource" when you're figuring out the address of the row that you want to refer to. So basically, if you want to refer to the row that is directly below the row with the "class_resource", then you would add "_$0" (to form "repeating_resource_$0"). And then the next row after that is "_$1", and so on.<br />
<br />
Third, keep in mind that if you add "_resource_left" (to form "repeating_resource_$0_resource_left"), then you are specifying that you are talking about the CURRENT VALUE of the leftmost resource in that row. And if you add "_resource_left_max", then you are specifying that you are talking about the MAX VALUE of the leftmost resource in that row.<br />
<br />
Here is a complete list of all the fields that you can access in the "repeating_resource" section. Just replace the "#" character with which row you want to access.<br />
<br />
<code>repeating_resource_$#_resource_left</code><br><br />
<code>repeating_resource_$#_resource_left_max</code><br><br />
<code>repeating_resource_$#_resource_left_name</code><br><br />
<code>repeating_resource_$#_resource_right</code><br><br />
<code>repeating_resource_$#_resource_right_max</code><br><br />
<code>repeating_resource_$#_resource_right_name</code><br><br><br />
<br />
<br />
'''Features/Class Traits'''<br />
<br />
<code>repeating_traits_$0_output<br><br />
repeating_traits_$#_name<br><br />
repeating_traits_$#_source<br><br />
repeating_traits_$#_source_type<br><br />
repeating_traits_$#_description<br><br />
</code><br />
<br />
'''Other/Settings'''<br />
<br />
<br><br />
<code><nowiki>wtype</nowiki></code> (whisper type, can have one of these values:)<br />
* <code><nowiki></nowiki></code> (empty for never whisper)<br />
* <code><nowiki>@{whispertoggle}</nowiki></code> (show the buttons on sheet that can toggle between options)<br />
* <code><nowiki>?{Whisper?|Public Roll,|Whisper Roll,/w gm }</nowiki></code><br />
* <code><nowiki>/w gm</nowiki></code> (always whisper)<br />
<br />
<br />
'''Global modifiers'''<br />
<br />
* <code>repeating_savemod_$0_global_save_roll</code><br />
* <code>repeating_skillmod_$0_global_skill_roll</code><br />
* <code>repeating_tohitmod_$0_global_attack_roll</code><br />
* <code>repeating_damagemod_$0_global_damage_damage</code><br />
<br />
====NPC====<br />
Some stats are the same as for PCs<br />
<br />
<code>npc_name<br><br />
npc_ac<br><br />
hp, hp|max<br><br />
npc_speed<br><br />
npc_challenge<br><br />
npc_xp</code><br />
<br />
Attributes: <code>strength_base, strength_mod</code> (same as PCs)<br />
Saves:<br />
<br />
<code>npc_str_save_base</code>,<code>npc_dex_save_base</code>, <code>npc_con_save_base</code>,<code>npc_int_save_base</code>,<code>npc_wis_save_base</code><code>npc_cha_save_base</code><br />
Skill bonus:<code>npc_acrobatics_base</code>, <code>npc_animal_handling_base</code> etc.<br />
<br />
Damage/Conditions stuff:<br />
<br />
<code>npc_vulnerabilities<br><br />
npc_resistances<br><br />
npc_immunities<br><br />
npc_condition_immunities</code><br />
<br />
Spells:<br />
<br />
<code>npcspellcastingflag</code> (set to "1" if caster, empty otherwise) <br />
<code>spellcasting_ability</code><br />
<code>globalmagicmod </code> (global magic attack modifier)<br />
<code>caster_level</code><br />
<code>spell_dc_mod</code> (spell save DC mod)<br />
<br />
Spells are identical to PC section<br />
<br />
Other:<br />
whisper is same as PCs<br />
<br />
<code>npc_name_flag</code> (show/hide npc name in rolls, value is either <code><nowiki>{{name=@{npc_name}}}</nowiki></code> or <code>0</code>)<br />
<br />
<br />
<sup>Note: anything with the Suffix of <code>|max</code> requires some form of Prefix, such as <code>selected|</code> making the call for such a thing look something along the lines of <code>@{selected|hp|max}</code>. The <code>|max</code> Suffix specifically calls the box on the right of the selected Attribute's Line, for example, you could fill in the Weight Total's 2nd Box with <code>@{strength}*15</code> & whenever you call <code>@{selected|weighttotal|max}</code> it will tell you your 5e standard Maximum Carry Capacity for your current Strength Score.<br />
<br />
===Custom AC Items===<br />
You can add pieces to your inventory and manually give them AC or magic bonuses that will figure into their calculations automatically. Inside the item options is a section for "MODS:". Add <code>Ac +1</code> to add an armor class bonus.<br />
<br />
===Roll Templates===<br />
''Main Article:'' '''[[D&D 5e by Roll20 Roll Templates]]'''<br />
<br />
The '''D&D5E by Roll20''' Character Sheet also includes a series of [[Roll Templates]] that you can use to dress up your own custom macros. Roll Templates provide additional layout and styling options for the display of roll results.<br />
<br />
{{ex}}<br />
[[File:5e-rolltemplate-ex1-2021.png|200px|right|none]]<br />
Rolls stealth for selected npc token, using it's stealth proficiency.<br />
<code><nowiki>/w gm &{template:npcatk} {{attack=1}} {{name=Shadow}} {{rname=Shadow Stealth}} {{rnamec=Hide}} {{r1=[[@{selected|d20}+@{selected|npc_stealth} + 6]]}} {{always=1}} {{r2=[[@{selected|d20}+@{selected|npc_stealth} + 6]]}} {{description=While in dim light or darkness, the shadow can take the Hide action as a bonus action. Its stealth bonus is **also** improved to +6 }}</nowiki></code><br />
<br />
===Magic Missile Spell===<br />
{| role="presentation" class="wikitable mw-collapsible mw-collapsed" style="float:right; margin-left: 10px;margin-right: 60px;"<br />
| Image of the Spell's settings<br />
|-<br />
| [[File:Magic-Missile-5E-2020.png|right|frame|The Magic Missile Spell]]<br />
|}<br />
<br />
RAW, Magic Missile is rolled once, and the single roll is then used for each hit. So by default the spell rolls <code>1d4+1</code>. (See [[Talk:D&D 5E by Roll20#Old Magic Missile Discussion]] for more info.)<br />
<br />
You can modify the spell to instead roll 3d4+3 at first level, and then in the ''HIGHER LVL CAST DAMAGE'' section, set it to <code>1d4+1</code>.<br />
<br />
To automatically use higher-level spell slots with Magic Missile, you have to write a 0 into the ''HIGHER LVL CAST DAMAGE'' section of the spell and select any die. It will show the box for selecting higher-level spell slots when launching Magic Missile, but since it multiplies the higher-level damage cast by 0, the added roll doesn't show up in the chat, making it roll a single die for every missile while using any level spell slot.<br />
<br />
=API=<br />
{{pro only|section}}<br />
[[API:Introduction|API Scripts]] allow for greater customization and functionality to how Roll20 operates beyond what it can do at default. This section will list some info on using various APIs that interact with the character sheet.<br />
<br />
Example of APIs from the One-Click Install menu, that designed to be used with the '''D&D 5E by Roll20''' sheet:<br />
* '''5E BattleMaster'''<br />
* '''5E Resting in Style'''<br />
* '''CashMaster'''<br />
* '''Concentration'''<br />
* '''[[Script:It's a Trap|It's a Trap! -- D&D 5E Generic]] (should detect automatically what sheet is used)<br />
** {{repo|Roll20/roll20-api-scripts/tree/master/ItsATrap_theme_5E_Generic#readme readme}}<br />
* '''ShortRest'''<br />
* '''SpellMaster'''<br />
* '''WildShape'''<br />
<br />
A good number of the more general APIs have built in settings for configuring them for usage with the 5E sheet, such as '''GroupInitiative''', '''GroupCheck''', '''Experience Tracker''', '''[[PowerCards]]''', '''[[ScriptCards]]''' (ScriptCards is an improved version of PowerCards)<br />
<br />
* '''[[GroupCheck]]:''' <code>!group-check-config --import 5E-OGL</code> will configure the API for use with this sheet<br />
* '''[[GroupInit|GroupInitiative]]:''' before use, API need to be configured for the sheet, either through the menu preset, or using the command: <code>!group-init --add-group --Bare </code><br />
* '''CombatMaster:''' is by default configured with conditions for D&D 5E<br />
* '''[[ChatSetAttr]]:''' API that can create, edit, & delete stats on sheets. Example: [[Script:ChatSetAttr#Add_new_thing_to_Repeating_Section|Adding a new magic item to a sheet]], with one chat command <br />
* '''[[Script:Ammo]]''' can be used for updating ammo & spellslots when used<br />
<br />
==Utilizing the ''5th Edition OGL by Roll20 Companion'' API Script==<br />
'''{{repo|Roll20/roll20-api-scripts/tree/master/5th%20Edition%20OGL%20by%20Roll20%20Companion 5th Edition OGL Companion}}'''is an official companion script for the "D&D 5E by Roll20" character sheet. The Companion currently supports Ammo Tracking, Automatic NPC Tokens, Automatic Death Save Tracking, and Automatic Spell Slot Tracking. <br />
<br />
{{mbox | text = Installing & creating [[API]] Scripts is a {{Pro}} feature. In order to be able to access these advanced scripts, the [[GM]] of the campaign must be a [[Pro]] subscriber and enable it for their campaign.}}<br />
<br />
<br />
'''''How to Add the API Script to your Game'''''<br />
<br />
If you have a PRO account, you can install the API script by going to your game's Campaign Page and clicking on the '''Settings''' button, and then choosing '''API Scripts'''. This brings you to the API Scripts page for your current game. The Companion Script is part of the One-Click Community API Installation options. Under the Script Library tab, there is a drop down menu that lists all the available community created scripts. Scroll down till you find the '''System Toolbox''' category and select the "5th Edition OGL by Roll20 Companion" script. The version number, the script's author, and a brief description of what the script does will appear right below the drop down menu once it is selected. Below that, click on the blue "Add Script" button to add the script to your game.<br />
<br />
<br />
'''''List of API commands for the 5th Edition OGL Companion API Script'''''<br />
* <code>!5ehelp</code> - Gives a list of the script's API commands in the chat tab.<br />
* <code>!5estatus</code> - Lists the current status of the script's features in the chat tab.<br />
* <code>!ammotracking on/off/quiet</code> - Automatically expends linked resource when attack is made<br />
* <code>!autonpctoken on/off</code> - Automatically generates a NPC token on the GM's screen based on the default token when an NPC's health calculation is rolled<br />
* <code>!deathsavetracking on/off/quiet</code> - Automatically ticks off successes and failures when death saves are rolled, clearing on death, stabilization, or hp recovery<br />
* <code>!longrest <character name></code> - This will add Hit Dice recover and if spelltracking is on, this command will reset all of the character's spell slots to unspent.<br />
* <code>!npchp <character name></code> - Rolls NPC hit point totals using their formula and updates the token bar. If no character name is provided it will roll the selected tokens.<br />
* <code>!spelltracking on/off/quiet</code> - Automatically expends spell charges as cast, factoring in higher level casting, and spells marked as Rituals will not spend a spell slot.<br />
<br />
<br />
Options:<br />
* ''on'' - Toggles the functionality on (default)<br />
* ''off'' - Disables the functionality<br />
* ''quiet'' - Maintains functionality while preventing results from being output to the chat.<br />
<br />
<br />
===Automatic Ammunition Tracking===<br />
''Main Article:'' '''[[D&D 5E by Roll20: How to setup Ammunition and Resource tracker]]'''<br />
<br />
Automatic Ammunition Track is a feature that requires the above Companion API Script. Once installed, follow these instructions to enable automatic ammunition tracking in your game:<br />
<br />
This example sets up a Longbow with a quiver of Arrows to track.<br />
# On the Settings (Gear Icon) tab of a character sheet, under GENERAL OPTIONS, make sure that the INVENTORY option is set to "Compendium Compatible" and not "Simple".<br />
# While still under GENERAL OPTIONS, set the AMMO TRACKING feature to ON.<br />
# Create manually or drag a missile weapon (ex. Longbow) from the Compendium to your sheet.<br />
# Create manually or drag a missile type (Arrows) from the compendium to your sheet<br />
# Expand the missile type (Arrows) by clicking on the "I" information icon that appears when hovering the mouse over the item.<br />
# Select the USE AS RESOURCE checkbox. (ammunition items dragged from the Compendium will have this option automatically checked off)<br />
# On the CORE tab, expand the missile weapon (Long Bow) in the ATTACKS & SPELLCASTING section by clicking on the gear icon that appears when hovering over the attack.<br />
# In the AMMUNITION section put the exact name of the ammunition resource (Arrows). If you want to spend more than one piece of ammunition per shot you want to add the number of pieces after the name of the ammunition resource and a comma. (ex. ''Arrows,2'' )<br />
<br />
<br />
Now, any time the missile weapon (Longbow) is rolled, a piece of ammunition will automatically be spent and the chat will make note. Additionally after the first time the missile weapon is used the AMMUNITION section will update with the ID of the resource repeating section, this is normal and expected.<br />
<br />
<br />
===Automatic Spell Slot Tracking===<br />
<br />
Automatic Spell Slot Tracking is a feature that requires the above Companion API Script. Once installed, follow these instructions to enable automatic spell slot tracking in your game:<br />
* In the chat input area of the Sidebar, type ''!5estatus'' and press Enter, to check if spelltracking is set to 'on'.<br />
* If not, type ''!spelltracking on'' and press Enter to activate this feature.<br />
* Alternatively, you may type ''!spelltracking quiet'' and press Enter to activate this feature, while preventing spelltracking messages from being displayed in the chat.<br />
<br />
<br />
<br />
Once the Spell Slot Tracking has been activated, each time a spell is cast:<br />
# The number of cast spells of the appropriate level is updated in the Spell tab of the character sheet (see [[5th Edition OGL by Roll20|Spell Levels & Spells Per Day]]).<br />
# A message is output in the chat, displaying the spell level, the number of available spell slots and the number of used spell slots for this level.<br />
# Spell slots decrement as spells are cast. <br />
# Spells that are marked as a Ritual do not affect the tally of spell slots when cast.<br />
<br />
<br />
At any time, you can manually adjust this count directly in the Spell Page of the character sheet.<br />
<br />
=Updates=<br />
* {{hc|articles/360037772613-Change-Log Roll20 Changelog}} - Full Changelog of Roll20, updates for 5E sheet are included<br />
* {{fpl|10096810/ D&D 5th Edition by Roll20 (Q2Y2021)}} often has mentions of latest updates<br />
* Major Sheet Updates:<br />
** Feats can now be selected in Charactermancer {{fpl|8891809 June 2020}}<br />
** Game [[creator]] can select which [[compendiums]] are or aren't accessible in a game. [https://app.roll20.net/forum/post/8738570/release-note-for-may-26-2020 May 26 2020]<br />
<br />
=Known Issues=<br />
The sheet has a number of known bugs and issues, some which are mentioned in the sheet's latest forum thread.<br />
<br />
'''Charactermancer/Character Creation'''<br />
* '''Charactermancer & Compendium drag-n-drop doesn't work when sheet is in a separate window.''' This is [[Character_Sheets#Character_Sheet_in_a_separate_window|an inherit limitation to how character sheets work]] at the moment. <br />
* '''Multiclassing & spell selection''' - There are troubles when multiclassing spellcasters and getting to select spells from the right lists.<br />
* '''Duplicate races/classes from Essential Kit appear in selection''' You need to uncheck EK from your compendium for it to no longer appear in selections.<br />
<br />
<br />
'''General:'''<br />
* '''Warlock spell slots''' - The Warlock's spell slots don't work too well with the sheet, and most people use some manual adjustments for how they work. The number of spell slots also appears wrong in the Charactermancer.<br />
* '''NPC stat <code>desc</code> changed into <code>description</code>''' This was a recent update that broke some macros for people, resulting in error messages along: "can't find ''desc'' attribute" {{fpl|8297517/ release notes march 2020}}<br />
<br />
=Sheet Guides=<br />
* [[5E Macros]]<br />
* {{blog|638339117446578176/tome-of-tips-dungeons-dragons-5th-edition-ogl Tome Of Tips: The D&D 5E character sheet}}<br />
* {{yt.be|9BGGr97qJdY|Learning Roll20: EP01 Character Sheets (D&D 5E)}} 50min, by Roll20 (2020)<br />
<br />
=Related Pages=<br />
* D&D 5E by Roll20 sheet<br />
** [[D&D5E by Roll20 NPC Attributes]]<br />
** [[D&D 5e by Roll20 Roll Templates]]<br />
** [[D&D 5E by Roll20: How to setup Ammunition and Resource tracker]]<br />
* [[5E]] - general D&D 5E info for Roll20. Lists also the alterantive character sheets for 5E<br />
* [[D&D]] - Roll20 stuff on the various editions.<br />
* {{Compendium}}<br />
** [[Compendium Sharing]]<br />
* [[Character Vault]]<br />
<br />
=See Also=<br />
* {{repo|Roll20/roll20-character-sheets/tree/master/DD5thEditionLegacy Sheet sourcecode}} - (Public version of sheet code is 1½+ years behind from what is actually used)<br />
* {{hc|articles/360037772613-Change-Log Roll20 Changelog}} - Full Changelog of Roll20, updates for 5E sheet are included<br />
<br /><br />
<br /><br />
[[Category:Character Sheet Documentation]]<br />
[[Category:Official Sheet]]<br />
[[Category:DnD5E]]<br />
[[Category:Featured articles]]</div>5004103https://wiki.roll20.net/D%26D_5E_by_Roll20D&D 5E by Roll202021-10-12T17:07:31Z<p>5004103: /* Dynamic References to Repeating Sections */</p>
<hr />
<div>{{revdate}}{{HCbox|{{hc|360037773573-5th-Edition-OGL-by-Roll20 D&D 5E by Roll20}} }}<br />
[[File:5E OGL Sheet Core v2.6.png|500px|thumb|right|The '''D&D 5E by Roll20''' Character Sheet]]<br />
<br />
This is the community-driven documentation for the '''[[5E|D&D 5E]] by Roll20''' character sheet. Previously the sheet was known as the '''"5th Edition OGL Sheet"''' or just the '''"OGL Sheet"'''.<br />
<br />
=The Basics=<br />
This page is a ''[[Community Wiki]]'' guide to the Official D&D 5th Edition character sheet, which is updated with info tricks that might not be covered by the {{hc|articles/360037773573-5th-Edition-OGL-by-Roll20 official sheet documentation}}.<br />
<br />
<br />
To find out about the latest updates, issues and talk about the sheet, check the {{fpl|10096810/ D&D 5th Edition by Roll20 (Q2Y2021)}}-thread on the {{forum|category/277980 forums}}.<br />
<br />
<br />
[[Bug|Bug reports]] for the sheet is best reported in the same thread. If you find bugs in the 5E Compendium or 5E marketplace content, {{bug}}.<br />
<br />
<br />
__TOC__<br />
<br />
==Adding the Character Sheet to a Game==<br />
[[File:D&D5E-Roll20-sheet-selection.png|300px|thumb|right|The Sheet Selection Menu]]An official or community contributed character sheet [[Add_character_sheet#Adding_a_Character_Sheet_to_your_Campaign|can be added to any game when you first create it]]. On the Game Creation screen, underneath the large blue '''“I’m Ready, Create Game!”''' button, is the '''“Optional: Choose a Character Sheet”''' section. Located here is a drop down menu that lists all the character sheets built either by Roll20 officially or created by the community. These sheets are sorted under their respective RPG Systems in alphanumerical order. Once selected, a preview of the character sheet will load upon the creation page for you to review as well as showcase relevant information about the sheet, such as the sheet’s creator and its key features.<br />
<br />
<br />
The '''D&D 5E by Roll20''' Sheet can be found under either: '''Sheets by Roll20''' → D&D 5E by Roll20 OR '''Dungeons and Dragons 5E''' → D&D 5E by Roll20<br />
<br />
<br />
If you want to add a character sheet to an existing campaign, you can find this drop down menu once again by accessing the [[Game Settings Page]] from the [[Game_Management#Game_Details_Page|Game Details]]-page.<br />
<br />
{{mbox | text = '''NOTE:''' If you have added custom attributes to your character journals prior to adding a character sheet to a campaign, you may want to delete them first. Adding a character sheet to a campaign will create its own set of custom attributes on all of your character journals, but it will reuse any attributes encountered if they share the same name. This can cause calculation issues on the sheet.}}<br />
<br />
<br />
If you were previously using either the [[DnD5e Shaped Character Sheet|D&D 5E (Shaped)]] or [[DnD5E_Community_Contributed|D&D 5E (Community Contributed)]] sheets and wish to transfer over to the '''D&D 5E by Roll20''' version, it's a good idea to ask help on the [https://app.roll20.net/forum/category/277980 forums].<br />
<br />
<div style="clear: both"></div><br />
<br />
==Where to Find the Sheet==<br />
Once a character sheet has been added to a game, and once inside it, on all [[Journal#Characters|Characters Journals]], a new tab will be available between the '''“Bio & Info”''' and '''“Attributes & Abilities”''' tab labelled '''“Character Sheet”'''. Much like the Attributes & Abilities tab, only players who have been granted Edit permissions for the journal entry will be able to access the Character Sheet tab.<br />
<br />
''See also:'' '''[[Add_character_sheet#Adding_New_Characters_In-Game|Create new character sheets to your players]]'''<br />
<br />
==Sheet Features==<br />
The '''D&D 5E by Roll20''' sheet has all of the functionality of a pen and paper character sheet, and much more. Certain aspects of the sheet have been streamlined or automated to remove bookkeeping and speed up gameplay. The key features are auto-calculations, [[Macro|macro]] buttons, and [[D&D 5e by Roll20 Roll Templates|roll templates]]. The sheet defaults to using the rules as printed in the D&D 5E SRD, however it's dynamic enough to allow you and your group to use many custom house rules you might want.<br />
<br />
===Auto Calculations===<br />
Many parts of the sheet use auto calculations to fill in derived attributes with the expectation that you're using the rules as printed in the 5th Edition SRD. Many of these calculated traits can be modified from the character sheet's <span style="font-family:Pictos;">y</span> [[D&D 5E by Roll20#Settings Page|Settings]]-tab, and those set by Sheet Workers can be edited directly. Below are some examples of Sheet Worker and Auto Calculation functionality:<br />
<br />
* '''Class''' - Changing the character's class from the header will automatically update the character's saving throw proficiencies, their hit die type, spell casting ability, and spell save DC. <br />
* '''Level''' - Changing the character's level will also update their proficiency bonus, number of spells per day, and more.<br />
* '''Attributes''' - Changing one of the character's attributes will also update the related modifier, skills that are based on that attribute, and derived stats such as initiative or passive perception.<br />
<br />
===Roll Buttons and Roll Templates===<br />
[[File:5E_OGL_Sheet_Rollable_Buttons.gif|right|frame|Any label that highlights in red when the mouse hovers over it is rollable.]]<br />
''Main Page:'' '''[[D&D 5e by Roll20 Roll Templates|D&D 5E by Roll20 Roll templates]]'''<br />
<br />
Most of the stats in the game can be rolled by hovering over their name, the stat will turn red, and then left-clicking the mouse. This is true for Attributes, Saves, Skills, Hit Dice, Death Saves, Tool Proficiencies, Attacks & Spellcasting, Spell Cards, and NPC Actions/Attacks. Any of these roll buttons can be dragged directly from the sheet to your [[Macro Quick Bar]], enabled from the <span style="font-family:Pictos;">y</span> [[My Settings]]-tab of Roll20's [[Sidebar]].<br />
<br />
Player characters have both a simple and attack [[D&D 5e by Roll20 Roll Templates|roll template]] that is output to the {{Text Chat}}-tab on the right hand [[Sidebar]]. The simple template is used for everything except for attacks. The attack template is shaped to show up in three pieces; the attack at the top, information in the middle, and damage at the bottom. Depending on your sheet settings, the damage will not roll automatically unless you click on the name of the attack from the roll template in the chat tab. This was designed to simulate the tabletop experience of rolling to attack and then rolling damage if necessary. You can change this behavior in the sheet <span style="font-family:Pictos;">y</span> [[D&D 5E by Roll20#Settings Page|Settings]]-tab, tab under "Auto Damage Roll".<br />
<br />
<div style="clear: both"></div><br />
<br />
====Rolling for Advantage and Disadvantage====<br />
With the '''D&D 5E by Roll20''' Sheet, the [[D&D 5E by Roll20#Settings Page|default sheet settings]] has Advantage set to ''always'' rolled for convenience purposes. It is commonly agreed upon that a gaming group uses the left roll result when advantage is not being used for a check. When advantage or disadvantage is in play, simply choose the higher or lower result among the two per usual. You can change this behavior in the sheet <span style="font-family:Pictos;">y</span> [[D&D 5E by Roll20#Settings Page|Settings]]-tab (gear icon at the top right of the page), tab under "Roll Queries". You have the choice of "Always Roll Advantage" (the default setting), "Advantage Toggle", "Query Advantage", or "Never Roll Advantage".<br />
<br />
'''Advantage Toggle:''' The Advantage Toggle will add three buttons to the top of your character sheet: "Advantage", "Normal", and "Disadvantage". You can click on any of these to roll for Advantage (the highest roll result will highlight in black), Disadvantage (the lowest roll result will highlight in black), or a single d20.<br />
<br />
'''Query Advantage:''' The Query Advantage setting will prompt a dialog box to appear whenever you roll from your sheet. It will ask you to select what sort of roll want to do (Normal, Advantage, Disadvantage). After choosing the type you want, the roll will occur in chat.<br />
<br />
'''Never Roll Advantage:''' When rolling from your sheet, only a single d20 will be rolled.<br />
<br />
===Resizable Text Fields===<br />
[[File:5E_OGL_Sheet_Resizable_Text_Fields.gif|right|frame|Making a text field larger is just a matter of click and dragging.]]There are many free-text fields on the sheet that give you a place to keep information that doesn't necessarily follow a specific format. All of the fields on the Bio Tab are free-text fields as well as the Description fields present for attacks, spells, equipment, features & traits, and NPC actions. If your text overflows past the bottom of a text field, you can resize it to view the content in its entirety by clicking and dragging the bottom right corner icon shown in the adjoining image.<br />
<br />
<br />
At present, these fields can only contain raw text. There are no formatting options (bold, italic, etc.) available.<br />
<br />
<div style="clear: both"></div><br />
<br />
===The Padlock Button and Organizing Elements===<br />
(aka. '''[[Character_Sheets#Repeating_Section|Repeating Section]]''')<br />
[[File:5E_OGL_Sheet_Padlock.gif|right|frame|The Padlock Toggle]]There is a <span style="font-family:Pictos;">(</span> (padlock) icon set at the bottom of several different fields of the '''D&D 5E by Roll20''' Sheet. It is used where a player is meant to add entries such as individual attacks, actions, pieces of equipment, features & traits, tool proficiences & custom skills, other proficiencies & languages, and spells. This icon behaves as a toggle button. <br />
<br />
When set in the <span style="font-family:Pictos;">(</span> locked position (default), a player can add new entries into the field. When the button is toggled to <span style="font-family:Pictos;">)</span>(unlocked), a player can no longer add new entries, but they will be able to reorder or delete any of the existing ones. The <span style="font-family:Pictos;">#</span>(red trash bin)-icon overlaid on the right hand side of the entry will delete it.<br />
<br />
{{Ambox<br />
|nocat=true<br />
| type = content<br />
| text = '''Deleting an entry cannot be undone!''' On left side of every entry while the padlock is <span style="font-family:Pictos;">)</span> unlocked is a re-sort icon symbolized by '''<big>≡</big>'''(three parallel lines). By clicking and dragging on this icon, you can rearrange the order of the entries in the field.<br />
}}<br />
<br />
{{Ambox<br />
|nocat=true<br />
| type = content<br />
| text = Some of the features of '''Repeating Sections''' do not work when the [[Character_Sheets#Character_Sheet_in_a_separate_window|Character Sheet is in a separate window]].<br />
}}<br />
<br />
<br />
<div style="clear: both"></div><br />
<br />
==Utilizing the 5th Edition SRD Compendium==<br />
[[File:5E_OGL_Sheet_Compendium.png|right|The Compendium Tab]]Upon adding the D&D 5E by Roll20 Character Sheet to a campaign, the [https://app.roll20.net/compendium/dnd5e/BookIndex| 5th Edition SRD Compendium] is automatically enabled for use from it's own <span style="font-family:Pictos;">i</span> [[Compendium]]-tab in the '''[[Sidebar]]''' of the application. It's located between the {{Journal}} and <span style="font-family:Pictos Custom;">u</span> [[Jukebox]]-tabs, and is accessible for both GM and Player alike.<br />
<br />
<br />
The <span style="font-family:Pictos;">i</span> [[Compendium]] allows for rapid searching of all rules, classes, monsters, spells, items, and more that are included in the 5th Edition SRD. This minimizes time spent for the gaming group to leaf through a book in the middle of a session for a rule clarification. Even better, both the GM and the Player can utilize dragging and dropping* from the <span style="font-family:Pictos;">i</span> [[Compendium]]-tab directly to your character sheets. This makes statting NPCs and PCs far faster than inputing everything manually.<br />
<br />
{{mbox | text = '''NOTE:''' The 5th Edition SRD is similar but NOT identical to the ''Dungeons and Dragons'' 5th Edition Rule Book. Some skills, classes, creatures, items, and other elements found within the ''Dungeons and Dragons'' rule book are strictly intellectual property of Wizards of the Coast and not accessible through their Open-Game License(OGL).}}<br />
<br />
<br />
===Statting PCs===<br />
Dragging from the <span style="font-family:Pictos;">i</span> [[Compendium]] works for the Equipment and Spell fields of the PC Sheet. This will not only carry over the name of the item or spell, but the relevant attack and damage rolls and any rules or flavor text that comes with it. Adding Compendium items in this fashion also automatically adds the equipment item (if it's a weapon) or spell to the Attacks & Spellcasting field to roll directly from. Items that modify a character's Attributes, Saves, AC, To Hit, Damage, Spell Attacks, and Spell DC will be automatically calculated on the sheet when dragged in. For example, if a Belt of Giant Strength is dragged to a sheet, the strength Attribute Score will become highlighted in blue and its attribute score will be increased. An asterisk is appended to the right of the score to also signify that it has been modified by an item. When you mouse over this number, the strength Attribute Score will revert back to what its unmodified total so you can refer back to it. Dropping a Compendium items that is an ammunition type (arrows, crossbow bolts, blowgun darts, etc) will automatically fill out a resource field for that item and link it to its entry in the Equipment section.<br />
<br />
To insert a Compendium item into the character sheet, run a search for the Item or Spell you want to add in the <span style="font-family:Pictos;">i</span> [[Compendium]]-tab. Once found, click and drag on the Compendium item's name so that it creates a little named tile that follows along with your mouse. Drag this over to the character sheet, it doesn't matter where. A text box that reads, "ACCEPTING DROP FROM COMPENDIUM" will appear on your sheet if this is done correctly. Let go of the tile and the entry will be auto-completed with all the data pertaining to the the Compendium entry in the correct location on the sheet. You can see this in action below under [[#Equipment|Equipment]].<br />
<br />
===Statting NPCs===<br />
You can fill out an entire NPC sheet in a single drag and drop. Run a search for the NPC you want to create from the <span style="font-family:Pictos;">i</span> [[Compendium]]-tab. Once found, click and drag on the NPC name so that it creates a little named tile that follows along with your mouse. Drag this to anywhere over the Tabletop area of the screen. Let go of the tile and a new character journal will be created named after the NPC from the Compendium entry. Its sheet will be changed over to the NPC sheet and filled with the entire NPC entry from the Compendium including their Actions, Reactions, and Legendary Actions if applicable. If you're using one of the Compendium expansions bought from the Roll20 Marketplace like the Monster Manual or Volo's Guide to Monsters, token art will also be pulled from the Compendium entry, placed on the table, and linked to your NPC's journal.<br />
<br />
You can also drag an NPC entry from the Compendium to an existing journal entry if you have the sheet open. If the sheet is in PC sheet mode, it will automatically change it over to the NPC sheet, and add its entry elements to it.<br />
<br />
One thing to note about dragging a stat block over from the Compendium is that it uses an ''additive'' behavior. It will not replace anything that you have already entered manually.<br />
<br />
=The PC Sheet=<br />
The '''D&D 5E by Roll20 Sheet''' contains both the PC Sheet ''and'' the NPC Sheet. By default, a new character journal is set to the PC sheet, but you can switch between the two by toggling it from the [[#Settings Page|General Options Settings]]. The PC Sheet is split up into four pages and can be selected from the buttons just underneath the header at the top of the sheet. They are listed from left to right order: The [[#Core Page|Core Page]], The [[#Bio Page|Bio Page]], The [[#Spells Page|Spells Page]], and The [[#Setting Page|Setting Page]].<br />
<br />
== Creating and Leveling up a character with Charactermancer ==<br />
Players and GMs using the '''D&D 5E by Roll20''' Sheet can use the Charactermancer to create and level up characters.<br />
<br />
'''How to use the Charactermancer for [[Charactermancer (D&D Fifth Edition)|character creation and leveling]].'''<br />
<br />
<br />
{{Ambox<br />
|nocat=true<br />
| type = content<br />
| text = The Charactermancer do not work when the [[Character_Sheets#Character_Sheet_in_a_separate_window|Character Sheet is in a separate window]].<br />
}}<br />
<br />
==Core Page==<br />
[[File:5E_OGL_PC_Core_Guide.jpg|right|frame|The Core Page]]The Core Page is selected by default and has most of the information you'll want to use on a regular basis to play your character. This should look very similar to the content you would normally find on the first sheet of the physical "D&D 5E by Roll20" player character sheet. The screenshot at the top of this wiki page displays the entirety of the Core Page. <br />
===(1) Core Header===<br />
[[File:D&D5E-Roll20-core-header.png|550px]]<br />
<br />
The header block at the top of the sheet changes based on the page you have selected. On the Core page you can select a class by its dropdown menu. The available options from the dropdown are: Barbarian, Bard, Cleric, Druid, Fighter, Monk, Paladin, Ranger, Rogue, Sorcerer, Warlock, and Wizard. You can create a custom class from the Settings Page.<br />
<br />
Once a class has been selected you can update the class's level by changing the number next to the class. The sheet will also automatically mark the abilities that class has proficiency in as well as automatically select the dice that will be used when Hit Dice are rolled. You can change the Hit Dice setting manually from the options menu. If your character multi-classes, then the secondary class and its level will appear beside the primary class. This Class and Level field can hold up to four classes if desired.<br />
<br />
The fields for Background, Race, Alignment, and Experience Points allow you to fill in whatever text you wish to put in them. The Character Name persists over all pages of the sheet and is tied to the name you give to the journal entry. Changing it on the sheet itself will also change the name on the character journal and vice versa once it is closed.<br />
<br />
===(2) Attributes===<br />
<br />
[[File:5E_OGL_Sheet_Attribute_Block.jpg|left]]Along the left side of the sheet are listed the 6 primary attributes: Strength, Dexterity, Constitution, Intelligence, Wisdom, and Charisma. These attributes are used by almost every other calculation on the sheet, as they are the core definition of a character. Each attribute block has the core attribute score, which can be changed by modifying the number in the oval at the bottom of each block, and, inside the square, the attribute modifier which is auto-calculated based on the score below it. All racial ability score increases must be manually added to the core attribute score using the settings "gear" symbol at the top of the page (where the Core, Bio, and Spells buttons are located.) The attribute modifier uses the following calculation to set the value:<br />
<br />
<br />
<code>[[floor((@{strength}-10)/2)]]</code><br />
<br />
The attribute can be referenced by its name, such as @{dexterity} while the attributes modifier can be referenced by adding the mod suffix, @{dexterity_mod}.<br />
<br />
<div style="clear: both"></div><br />
<br />
===(3) Inspiration===<br />
<br />
[[File:D&D5E-Roll20-inspiration.png|left]]You can track whether or not you have Inspiration by clicking the circle next to the Inspiration block at the top left of the Core page. This will toggle a dragon spiral icon on and off for indication purposes.<br />
<br />
<div style="clear: both"></div><br />
<br />
===(4) Proficiency Bonus===<br />
<br />
[[File:5E_OGL_Sheet_Proficiency.png|left]]Your character's proficiency bonus is listed near the top left of the page. You cannot modify this value manually, instead it is automatically set based off your character's over-all level. Your character's Level can be set by changing the number next to your Class name in the [[#header_info|Header]] at the top when on the Core page.<br />
<br />
<div style="clear: both"></div><br />
<br />
===(5) Saving Throws===<br />
<br />
[[File:5E_OGL_Sheet_Saving_Throws.png|left]]Next to the core Attributes on the left side of the page is a list of the same attributes to be used in making saving throws. To mark an attribute that your character has proficiency in for saving throws, check the box next to the appropriate attributes. When you select a class in the header section of the Core page it will automatically check the correct boxes for that class's proficiencies.<br />
<br />
You can add an additional field to Saving Throws to serve as a Global Save Modifier. An example is if the character is under the influence of the Bless spell and can roll a 1d4 in addition to the result of their saving throws. This is enabled from the Settings Page under General Options. Once enabled a seventh checkbox and field will be added at the bottom of the Saving Throws block with a text field to enter the additional die roll. For this example, you could enter "1d4[BLESS]" in the global checkbox's text field that you can enable when the character is under the effects of the Bless spell. The word between the brackets becomes a label that can be seen when you mouse over the roll result in chat. While this Global Save Modifier is checked, every roll made from the Saving Throws block and performing a Death Save will add this modifier to the result.<br />
<br />
<div style="clear: both"></div><br />
<br />
===(6) Skills===<br />
[[File:5E_OGL_Sheet_Skills.png|left]]<br />
To the right of the Core Attributes is a list of all of the character's Skills. Each skill can be rolled by clicking on the skill name. If you have proficiency in a specific skill, then you would check the box next to the skill name, this will automatically add your proficiency bonus to that skill's checks. Each skill also lists the core attribute, that is used in the roll calculations, next to it in parenthesis.<br />
<br />
You can set advanced skill options for the Settings page, such as skill expertise, flat bonuses from class archetypes or feats, as well as Jack of All Trades.<br />
<br />
<div style="clear: both"></div><br />
<br />
===(7) Armor Class, Initiative, & Speed===<br />
<br />
[[File:D&D5E-Roll20-AC-Init-Speed.png|left]]The Armor Class & Speed blocks at the top center of the page can be used to keep track of your Armor and Speed values. The Initiative block cannot be modified manually, but instead is auto-calculated based off your character's Dexterity. If you have any additional initiative modifiers you can add them on the {{gear}} [[#Settings Page|Settings Page]] under Initiative Modifier in the Class Options block.<br />
<br />
Armor Class can also be tracked automatically by using the [https://app.roll20.net/compendium/dnd5e/BookIndex Compendium] compatible inventory, on by default.<br />
<br />
You can configure a custom AC calculation using the {{gear}} [[#Settings Page|Settings Page]] under the Attribute Tracking section. It's listed as "Armor Class Tracking" and is set to "Automatic" by default. If you select Custom, you can select up to two different attributes to apply to the character's armor class.<br />
<div style="clear: both"></div><br />
<br />
====Using the Global AC Modifiers====<br />
If you check the "Show Global AC Modifier" field in the character sheet General Options settings, the sheet will display a repeating section to configure and apply different modifiers to AC. So, for example, if your character has a common bonus, such as from a spell or a conditional feat or fighting style, you can toggle that AC bonus from the character sheet directly.<br />
<br />
====Rolling for Initiative and the Turn Order Tracker====<br />
Clicking on the word INITIATIVE will roll that character's initiative score. If your players have [[Token|tokens]] linked to their character sheets, they can roll their initiative ''and'' simultaneously add their character and its initiative score to the {{Turn Tracker}} automatically. What is required of the player is that their linked token must be currently selected on the Tabletop before they roll off their sheet.<br />
<br />
If you would like to enable a tie breaker component to Initiative, there is an option to enable this from the [[#Settings Page|Settings Page]] under the "Attribute Options" block. What this does is that it will add your dexterity Attribute Score as a decimal value to your Initiative. So if you have a character with a dexterity attribute score of 14, your initiative modifier will change from a <code>2</code> to a <code>2.14</code>.<br />
<br />
===(8) Hit Points & Temporary Hit Points===<br />
[[File:5E_OGL_Sheet_HP.png|left]]The Current Hit Points and Temporary Hit Points blocks are used to keep track of your character's Hit Points (HP). Inside the Current Hit Points block, at the top, is a line that lists the character's maximum amount of HP. <br />
<br />
<br />
When your character takes damage, if they have any, it should be subtracted from their Temporary Hit Points first, then any remaining damage would then come off of the character's Current Hit Points.<br />
<br />
<div style="clear: both"></div><br />
<br />
===(9) Hit Dice===<br />
[[File:5E_OGL_Sheet_Hit_Dice2.png|left]] The Hit Dice block is used to keep track of and roll your character's hit dice. Inside the Hit Dice block, at the top, is a line to keep track of the total number of dice your character can have. In the main area of the block you would keep track of the remaining hit dice. Clicking the "HIT DICE" label will roll the hit dice for your selected class automatically. If you wish to change the dice that is rolled you can do so in the Class Options section of the [[#Settings Page|Settings Page]] ({{gear}} icon). <br />
<br />
<br />
If your character is multi-classed, when rolling your hit dice (by clicking "''HIT DICE''", a pop-up will ask which of your character's current class's hit dice you want to roll. This input accepts only numerals a input to make automatic tracking of the [[API:A Guide to the API|API]] possible.<br />
<div style="clear: both"></div><br />
<br />
===(10) Death Saves===<br />
[[File:5E_OGL_Sheet_Death_Saves.png|left]]The Death Saves block is used to keep track of your character's death save rolls once they have been knocked out. You can click the "DEATH SAVES" label to make a death save roll. If you roll greater than 10 you would check one of the boxes next to "Successes" otherwise you would check a box next to "Failures". If your character has any modifiers to their death save rolls they can be added in the Class Options section of the Settings Page(gear icon).<br />
<div style="clear: both"></div><br />
<br />
===(11) Attacks & Spellcasting===<br />
[[File:5E_OGL_Sheet_Attacks_And_Spellcasting.png|left]]The Attacks & Spellcasting block in the center of the Core page of this character sheet will be one of the most often used sections. To start, you can manually add any attack or spell to this section by hovering over the block and clicking the "Add" button(the <span style="font-family:Pictos;">&</span> symbol). This will open a form that can be filled out with all of the information about the specific attack or spell you are adding. <br />
<br />
<br />
This section will automatically add attacks, with all the stats, for spells that have an attack component when they are added to your spell sheet on the [[#Spells Page|Spells Page]]. This happen both if you add the spell manually or if you drag and drop a spell from the <span style="font-family:Pictos;">i</span> [[Compendium]]. An attack is also automatically created if you drag and drop an item from the Compendium into your sheet.<br />
<br />
<div style="clear: both"></div><br />
[[File:Poisoned Dagger 5e Attack.png|right|frame|An example of an attack form filled out for a physical attack using a +1 Poisoned Dagger]]For example, lets say Erin the Bold has a +1 Poisoned Dagger that has the stats of a regular dagger, but also metes out an additional 1d6 of poison damage alongside the typical 1d4 points of piercing damage. The image displayed to the right is how the attack would be set up:<br />
<br />
<br />
Since this is a [https://app.roll20.net/compendium/dnd5e/Items:Dagger#h-Dagger dagger], and daggers have the "[https://app.roll20.net/compendium/dnd5e/Weapons#h-Weapons Finesse]" attribute I can chose either STR or DEX for my bonus attribute. Erin is quicker than she is strong, so we will pick DEX as the attribute to attack with, as well as checking the "proficient" checkbox since Erin is experienced with using these sorts of weapons. She doesn't have any other gear that might make her attacks better, so we will leave the generic bonus between the attribute and proficiency blank, or 0. Being a +1 Poisoned Dagger means that it is also magical, so it gets a 1 in the magic bonus slot just below. A dagger can also be used as a thrown weapon, so we've added the weapon's throwing range info to the "Range" field. Since a weapon does damage, we have checked the first "Damage" checkbox and filled in the required fields. This dagger does 1d4 piercing damage + Erin's DEX mod + 0 bonus damage (this would be used for bonus damage on top of the magical +1) and it doesn't have anything to change the critical damage so we just put the same damage into the "crit" box. Because this dagger can also cause poison damage, we also check the second "Damage" checkbox and fill in the info for the 2nd set of damage. The poison does a flat 1d6 poison with no extra bonuses, so we've selected "-" to say there is no attribute that adds to this damage. This damage also doesn't have anything to make the crit different so we set that to 1d6 as well. There are no extra saving throws or effects that are included with this attack, so we leave these additional sections blank. <br />
<br />
These additional effect sections will be used more commonly with spells, like [https://app.roll20.net/compendium/dnd5e/Fireball#h-Fireball Fireball], where you would require a DEX save against your SPELL DC, which will be set according to your character's spell casting level. For a fireball, the save effect would be "half damage" and the "Description" would be something like "Hits all creatures within 20 ft of the explosion point".<br />
<br />
After you are done modifying all of individual stats for an attack you can click the gear icon at the top right of that section and it will hide the stats for that attack. If ever you need to change these stats in the future you can hover over the entry and click the <span style="font-family:Pictos;">y</span>(gear)-icon that shows up to unhide the stats section. <br />
<br />
<div style="clear: both"></div><br />
====Adding Global Attack and Damage Modifier====<br />
You can add two special entries to the Attacks & Spellcasting block to handle to global Attacks and Damage modifications to rolls. An example is if the character is under the influence of the Bless spell and can roll a 1d4 in addition to the result of their attack roll. This is enabled from the [[#Settings Page|Settings Page]] under General Options. Once enabled, a checkbox will be added at the bottom of the Attacks & Spellcasting block with a text field to enter the additional die roll. For this example, you could enter <nowiki>"1d4[BLESS]"</nowiki> in the global checkbox's text field that you can enable when the character is under the effects of the Bless spell. The word between the brackets becomes a label that can be seen when you mouse over the roll result in chat. While these Global Modifiers are checked, every roll made from the Attacks & Spellcasting block will add these modifiers to the result.<br />
<br />
====Rolling from the Attacks & Spellcasting Block====<br />
[[File:Poisoned Dagger 5e Roll.png|frame|An attack roll from a +1 Poisoned Dagger]]Rolling from the Attacks & Spellcasting Block is no different than rolling from any other portions of the character sheet. Hovering your mouse over any entry here will highlight its entire label (NAME, ATK, and DAMAGE/TYPE) in red and you'll be able to click on it to roll the attack or spell. You can also drag this entry into the Macro Bar to give yourself easy access to this attack. Because this is a repeating section, the macro name will be a bit messy, but you can right-click the button and rename the macro to whatever you like.<br />
<br />
With any attack that checks for AC, you will see TWO rolls set side by side for the Armor Class check with the name of the attack listed underneath them with the Attack modifier bonus (ATK) appended to the Attack name in light grey. The Roll20 D&D 5E Character Sheet ''always'' rolls for Advantage by default, so you will always have two roll results for this check (most gaming groups use the left roll result if neither Advantage or Disadvantage is being factored in the check). If there is a specified range for the attack, this will be listed above the attack's name.<br />
<br />
Underneath the AC Check and Attack Name is the Damage roll result for the attack. Underneath this roll result will be the Damage Type (ex. slashing, piercing, poison, fire, etc.) listed in light grey italicized font.<br />
<br />
For spells that don't check for AC and instead require a Saving Throws to mitigate or negate the spell's effect, the SPELL DC is listed first. Underneath this, in italicized font, is the effect if a character succeeds the check listed. Underneath the effect is the required attribute saving throw that must be rolled. If Damage is applied, this result is rolled and listed next with its Damage Type.<br />
<br />
[[File:5e_attack_example.gif|right|frame|How to view attack damage when the sheet is set to "Don't Auto Roll Damage"]]<br /><br />
<br />
<br />
{{mbox | text = '''NOTE:''' If your character sheet's Settings have "Auto Damage Roll" set to "Don't Auto Roll Damage" under General Options, the damage will not be listed underneath the AC roll result in chat. The damage was rolled, but presently hidden from view. Anyone can see the damage delivered by manually unfolding the roll result open by hovering your mouse over the roll result in chat and clicking on the attack/spell's name.}}<br />
<div style="clear: both"></div><br />
<br />
===(12) Personality Traits, Ideals, Bonds, and Flaws===<br />
These text fields lock to prevent accidental edits. When a sheet is first created, these fields are unlocked and given a dashed yellow border to the top of the field to showcase that they're editable. To lock the field after entering text, click on the gear icon in the upper right corner of the field. This will remove the yellow border and the field will conform in height to display everything within it.<br />
<br />
There presently isn't a means to format the raw text (italicize, bold, font alignment, etc) within these fields and any line breaks are stripped out. If you ever need to edit the content again while the field is locked, mouse over the desired field and the gear icon will reappear in the top right. Clicking on that will unlock the field once again for edits.<br />
<br />
===(13) Class & Other Resources===<br />
[[File:5E_OGL_Sheet_Resources.png]]<br />
<br />
The Class & Other Resource Blocks can be used to keep track of either an item quantity you have in your equipment (like arrows in a quiver), or skills that don't fit into the other sections on the sheet (like a '''Sorcerer's Sorcery Points''', a '''Cleric's Channel Divinity''' at higher levels, or the number of rounds a '''Barbarian''' has been '''Raging''' so far in a combat encounter).<br />
<br />
There are 3 fields per Block:<br />
* Resource Max:<br />
** The Resource Max field is a text box which allows you to quantify exactly what you're tracking (ex. "Total: 10 Rounds").<br />
* Resource:<br />
** The Resource field is a numeral that you dial up or down or input directly.<br />
* Resource Name:<br />
** The Resource Name is a text box that allows you to label the resource when you click on the light grey "OTHER RESOURCE" label to overwrite it with your own.<br />
**"OTHER RESOURCE" is placeholder text<br />
<br />
<br />
A resource block will be filled automatically if you checkmark an Equipment item as "USE AS A RESOURCE" & the Item Quantity field will be paired with the Resource field in the Resource block & vice versa (you'll need to click outside of the field or hit Enter for changes to refresh across the sheet). If the two resource blocks given by default are not enough then you can add additional blocks by hovering over the section & clicking the "Add" (+ symbol) button.<br />
<br />
The Item Name will also be added to the Resource Name field, however the Resource Max field is apparently not linked to the Item currently.<br />
<br />
If you drag & drop an ammunition item type from the Compendium into your character sheet, the item is added to the Equipment block & is automatically listed & linked as an Other Resource.<br />
<div style="clear: both"></div><br />
To call the first set of class resources use:<br />
* Class Resource <code>@{class_resource}</code><br />
* Other Resource <code>@{other_resource}</code><br />
<br />
<br />
To call the Repeating resources use<br />
* Repeating Resource 1st left<code>@{repeating_resource_$0_resource_left}</code><br />
* Repeating Resource 1st right<code>@{repeating_resource_$0_resource_right}</code><br />
* Repeating Resource 2nd left<code>@{repeating_resource_$1_resource_left}</code><br />
* Repeating Resource 2nd right<code>@{repeating_resource_$1_resource_right}</code><br />
* etc.<br />
<br />
<br />
If you want to do a basic Full Readout of the Repeating Resource, the Format would be (Top Left to Bottom Right):<br />
* Class: <code>@{class_resource_name}: @{class_resource} / @{class_resource|max}</code><br />
* Other: <code>@{other_resource_name}: @{other_resource} / @{other_resource|max}</code><br />
* Left 0: <code>@{repeating_resource_$0_resource_left_name}: @{repeating_resource_$0_resource_left} / @{repeating_resource_$0_resource_left|max}</code><br />
* Right 0: <code>@{repeating_resource_$0_resource_right_name}: @{repeating_resource_$0_resource_right} / @{repeating_resource_$0_resource_right|max}</code><br />
* Left 1: <code>@{repeating_resource_$1_resource_left_name}: @{repeating_resource_$1_resource_left} / @{repeating_resource_$1_resource_left|max}</code><br />
* Right 1: <code>@{repeating_resource_$1_resource_right_name}: @{repeating_resource_$1_resource_right} / @{repeating_resource_$1_resource_right|max}</code><br />
* etc.<br />
<br />
===(14) Tool Proficiencies===<br />
[[File:5E_OGL_Sheet_Tool_Proficiencies.png|left]]The Tool Proficiencies block is for listing a character's Tool Proficiency skills. At the bottom of this block is an "Add" (<span style="font-family:Pictos;">&</span> symbol) button. Clicking this will add a new entry to this block where you can add all of the relative stats for a specific tool proficiency, say Woodcarver's Tools. You can set the level of proficiency to either Proficient, Expertise, or Jack of All Trades. The roll bonus for that tool will reflect the proficiency level selected. Next is an Attribute drop down menu where you can select which character attribute to roll with for a proficiency check. One of the options you can choose is "QUERY ATTRIBUTE" which when you click on the Tool Proficiency to roll it, you will be prompted to choose which attribute you would like to use. The attribute used for the check will be up to the GM when it is time to make the roll check. If there is any additional bonus modifiers that come along with the tool in question, you can input it in the "MODS:" field.<br />
<br />
Once you finished filling out the stats for this tool you can click the <span style="font-family:Pictos;">y</span>(gear) icon at the top right of the entry to hide the stat fields and leaving behind just the rollable button. You can roll by either clicking on this rollable button or dragging it to your [[Macro Bar]].<br />
<br />
You can also use this section to create custom skills or rolls for your campaign setting or home-brew ruleset. Check out the [[#Custom Skills and Stats|Advanced Use]] section for further details.<br />
<br />
====Global Skill Modifier====<br />
You can add a special entry to the Tool Proficiencies & Custom Skills block to handle to global Attacks and Damage modifications to rolls. An example is if the character is under the influence of the Guidance spell and can roll a 1d4 in addition to the result of their skill check. This feature is enabled from the [[#Settings Page|Settings Page]] under General Options. Once enabled, a checkbox will be added at the bottom of the Tool Proficiences & Custom Skills block with a text field to enter the additional die roll.<br />
<br />
For this example, you could enter "1d4[Guidance]" in the global checkbox's text field that you can enable when the character is under the effects of the Guidance spell. The word between the brackets becomes a label that can be seen when you mouse over the roll result in chat. While this Global Modifier is checked, every roll made from the Tool Proficiencies & Custom Skills block and the Skills block will add this modifier to the result.<br />
<div style="clear: both"></div><br />
<br />
===(15) Other Proficiencies & Languages===<br />
[[File:5E OGL Sheet Proficiencies.png|left]]<br />
This block can be set up to be Compendium Compatible (where you can add repeating sections for individual items) or as one resizable free-text field to enter whatever you wish in here. If you don't feel the Tool Proficiency block is needed (as in, you don't feel like your party will ever have to roll individual tool sets), you can store a character's Tool Proficiencies here instead. There presently isn't a means to format the raw text (italicize, bold, font alignment, etc). You can adjust this block's behavior by going to the Settings Page of the sheet and going to the General Options block to change whether this block uses the Simple or Compendium Compatible layout.<br />
<br />
When the Other Proficiences & Languages block is made Compendium Compatible, each repeating field lists a Type selection field and a Proficiency text field. Type has the following options available from its drop down selection menu: Language, Weapon, Armor, Other. <br />
<p style="clear:both;"></p><br />
<br />
===(16) Equipment===<br />
[[File:5E OGL Sheet Equipment.png|framed|right|The Equipment block of the PC Sheet]]<br />
The Equipment block at the bottom of the page has 2 different versions: a Simple version that features a single plain text field where you can track all of your equipment in any format you wish and a Compendium Compatible version that allows you to drag and drop items from the Compendium to automatically populate repeated sections for each indivdual piece of equipment.<br />
<br />
To swap between the two different Equipment block versions, first, go to the sheet's Settings Page (gear icon at the top right of the page) and then to the "General Options" section. Here, on the field labeled "Inventory", you can select between "Simple" or "Compendium Compatible" respectively. Like the name implies, if you want to be able to copy items directly from the Compendium using drag and drop, you must use the Compendium Compatible version. Dragging item entries from the Compendium to the character sheet will add it fully filled in the Equipment section as well as other automated actions described below.<br />
<br />
====Automated Compendium Functionality====<br />
If you populate the Equipment block by dragging and dropping <span style="font-family:Pictos;">i</span> [[Compendium]] items, there are several automatic features that occur when the entries you drag in our equipment items.<br />
Auto-Equip: Every item dragged to the sheet is automatically equipped in the Equipment Section<br />
*'''Weapons:''' A weapon dragged in from the Compendium will add an attack in the Attacks and Spellcasting section for that item.<br />
*'''Armor:''' Armor that is dragged in from the Compendium will add its bonus to the Armor Class (while equipped) section. If you drag multiple pieces of armor to the same sheet and at least two armor entries are equipped at once, a warning will pop up in red at the top of the Equipment Block that the Armor Class isn't being correctly calculated because of the bonus overlap. This warning will dissapear when you unequip down to a single set of armor.<br />
*'''Magical/Wondrous Items:''' Items that modify Attributes, Saves, AC, To Hit, Damage, Spell Attacks, and Spell DC will add that bonus to those elements on the sheet. In most cases, the attribute that is being modified will highlight in blue and followed with an asterisk to showcase that the attribute is being modified by an item. Mousing over the modified number will display the base value of that attribute before the item's modification is applied. This stat modification only applies if the item is equipped in the Equipment section and it will remove its bonus if it is unequipped.<br />
*'''Ammunition:''' Items dragged in from the Compendium that are used for ammunition such as arrows, bolts, darts, and slingstones, will automatically populate and link to an Other Resource field.<br />
<br />
====Manually Adding Items====<br />
You can also add items manually by hovering over the block and clicking the "Add" button (+ symbol). Each equipment entry, by default, show fields for quantity, name, and weight of an item. If you hover over a row and click the small "information" icon (grey-filled circle with a lowercase i centered in it) that appears at the bottom right of the entry you can also set some additional features. <br />
<br />
*'''Equipped Checkbox:''' The checkbox changes the appearance of the Item Name so it's easier to tell what your character currently has equipped from a glance. When left unchecked, the Item Name's font turns grey. When checked, the Item Name becomes a solid black.<br />
*Use As A Resource Checkbox: When checked, this will enable one of the Class Resource blocks and list the item name and its quantity within it. The quantity is tied between the two so changing it in one will be reflected in the other field after clicking outside the field.<br />
*'''PROP:''' This is a text field where you would take note of weapon properties such as ''finesse'', ''versatile'', or ''light''.<br />
*'''MODS:''' This is a text field where you would take note if an item (likely magical) would modify your stats in some fashion such as a character's Attributes, Saves, Skills, AC, To Hit, Damage, Spell Attacks, and Spell DC. If a stat is modified here, its attribute value will become highlighted in blue and adjusted by the supplied modifier listed here. An asterisk is appended to the right of the value to also signify that it has been modified by an item. While your mouse is hovering over the attribute, it will revert back to its unmodified total so you can refer back to its pre-moddified value.<br />
**The format for a stat modification is ''stat name:n'' where n is the stat bonus (ex. ''Strength:21'')<br />
*'''Description Field:''' This is a simple text field to include a description of the particular item and of any special qualities or effects it might have on the player.<br />
Some if not all of these fields will be filled in automatically when adding from the Compendium (where applicable).<br />
<br />
Both versions of the equipment field have the sections for each of the [https://app.roll20.net/compendium/dnd5e/Treasure#h-Treasure coins] you may find on your adventures: copper(CP), silver(SP), electrum(EP), gold(GP), and platinum(PP).<br />
<br />
====Encumbrance====<br />
If you are following Encumbrance rules, the <span style="font-family:Pictos;">i</span> [[Compendium|Compendium Compatible]] Equipment block will automatically calculate and track the weight of your character's backpack if you enter the weight values for any of the items in your Equipment list. When your character becomes encumbered, and depending on its severity, the words ENCUMBERED, HEAVILY ENCUMBERED, or IMMOBILE will display in red underneath the TOTAL WEIGHT value. You can also choose to follow Simple, Variant Encumbrance rules, or not follow Encumbrance rules at all by toggling it off on the [[D&D 5E by Roll20#Settings Page|Settings Page]] under "General Options".<br />
<br />
====Mods====<br />
The Mods field of each piece of equipment can modify the values of ability scores, AC, saving throws, Skill (Ability) checks and more. What follows is a list of the modifiers, and the proper syntax for adding them.<br />
<br />
All modifiers are separated by commas. There are other modifiers that can appear the mod field, used in creating the item from a compendium drag and drop operation, but the modifiers below have live effects on the character sheet, depending on if the item is marked as “equipped”.<br />
<br />
'''replace the <code>+n</code>, with the number you want.''' For example, if you want to boost Animal Handling skill by 3, you look at the table and find <code>Animal Handling +n</code>, so you will add to your item <code>Animal Handling +3</code>.<br />
<br />
{| class="wikitable" <br />
|-<br />
! Modifier<br /><br />
! Effect<br /><br />
|-<br />
| style="width: 20%;" | '''Combat Modifiers'''<br />
| '''These affect items that provide attacks (Appear in the attack section of the character sheet)'''<br />
|-<br />
| Melee Attacks +n<br />
| Adds +n hit "Magic Bonus" to that attack. It is not global, and only affects a weapon(melee or ranged), not an item, staff or other category. The bonus is figured into the attacks display on the 5e sheet.<br />It is NOT ''Melee Attack''.<br />
|-<br />
| Melee Damage +n<br />
| Adds +n damage "Magic Bonus" to that attack. It is not global, and only affects a weapon(melee or ranged), not an item, staff or other category. The bonus is listed separately in the attacks display on the 5e sheet.<br />
|-<br />
| Spell Attack +n<br />
| Adds a global +n to the character's Spell Attack bonus.<br />It is NOT ''Spell Attacks.''<br />
|-<br />
| '''Saving Throws'''<br />
| '''All modifiers stack with “Saving Throws +n'''<br />
|-<br />
| Strength Save +n,<br />Dexterity Save +n,<br />Constitution Save +n,<br />Intelligence Save +n,<br />Wisdom Save +n,<br />Charisma Save +n<br />
| Adds a +n to the indicated saving throw<br />''Do not use a colon.''<br />
|-<br />
| Saving Throws +n<br />
| Adds a Global Modifier to ALL saving throws.<br />
|-<br />
| Spell DC +n<br />
| Adds a global +n to a spell casting character’s Spell Save DC.<br />It is NOT Spell ''Save'' DC.<br />
|-<br />
| '''Ability Scores'''<br />
| <br />
|-<br />
| Strength +n,<br />Dexterity +n,<br />Constitution +n,<br />Intelligence +n,<br />Wisdom +n,<br />Charisma +n<br />
| Provides a bonus to the indicated ability score, which will appear in blue on the sheet while the bonus is active.<br />Do not use a colon. ''Strength: +10'' will do nothing<br />
|-<br />
| Strength n,<br />Dexterity n,<br />Constitution n,<br />Intelligence n,<br />Wisdom n,<br />Charisma n<br />
| Replaces the indicated ability score, which will appear in blue on the sheet while the bonus is active.<br />Do not use a colon. ''Strength: 10'' will do nothing<br />
|-<br />
| '''Skills'''<br />
| <br />
|-<br />
| Acrobatics +n,<br />Animal Handling +n,<br />Arcana +n,<br />Athletics +n,<br />Deception +n,<br />History +n,<br />Insight +n,<br />Intimidation +n,<br />Investigation +n,<br />Medicine +n,<br />Nature +n,<br />Perception +n,<br />Performance +n,<br />Persuasion +n,<br />Religion +n,<br />Sleight of Hand +n,<br />Stealth +n,<br />Survival +n<br />
| Adds the value to the indicated Skill roll. Note that in this case, the <code>+</code> and a colon are optional. <code>Acrobatics +5</code>, <code>Acrobatics 5</code>, <code>Acrobatics: +5</code>, <code>Acrobatics: 5</code> will all add <code>5</code> to the character’s Skill roll. For consistency and to guard against future functionality, it’s probably best to follow the format for ability scores, and use a plus sign with no comma: <code>Acrobatics +5</code>.<br />There is no Global Skill modifier<br />
|-<br />
| '''AC'''<br />
| <br />
|-<br />
| AC +n<br />
| By itself, <code>AC: 13</code> adds 13 to the character’s Armor Class. It does not replace it. <br /><br />If <code>Shield</code>, <code>Light Armor</code>, <code>Medium Armor</code>, or <code>Heavy Armor</code> is also in the mods field, it will change the calculation.<br />''<code>Light Armor, AC: 13</code>'' will give a formula of 13 + dex mod<br />''<code>Medium Armor, AC: 13</code>'' will give a formula of 13 + dex mod (max +2)<br />''<code>Heavy Armor, AC: 13</code>'' will give you flat AC 13<br />''Shield, AC: 13'' would add 13 to the your AC. The Shield keyword is superfluous in this case.<br />''<code>Shield, AC: 2</code>'' will just add 2 to the AC.<br />Finally, a bare modifier, such as for a Ring of Protection can just be written as <code>AC: +2</code> or <code>AC +1</code>.<br /><br />Shield or bare AC bonuses will stack with other armor mods on different items. You cannot equip multiple armors simultaneously, or have a custom armor equation on the settings tab and wear an armor. This will generate a flag.<br /><br />The + and a colon are semi-optional. <code>AC +5</code>, <code>AC: +5</code>, <code>AC: 5</code> will all work. However, <code>AC 5</code> will do nothing. For consistency and to guard against future functionality, it’s probably best to indicate a base AC as <code>AC: n</code> and a Shield as <code>AC +n</code>.<br />At this point, there is no way to differentiate between Ranged AC and Melee AC, though some magic items such as the ''Arrow Catching Shield'' make the distinction.<br />
|}<br />
<br />
<br />
<br />
<div style="clear: both"></div><br />
<br />
===(17) Features & Traits===<br />
[[File:5E OGL Sheet Features Traits.png|thumbnail|left|The Compendium Compatible itemized version of the Features & Traits section]]<br />
The '''Features and Traits '''-block is the place to store '''Class-''', '''Race-''' and '''Background Features''', '''Feats''', and other special notes about your character or of a certain piece of equipment or ability. When using the Charactermancer, the previously mentioned features appears in this section.<br />
<br />
This block can be set up to be <span style="font-family:Pictos;">i</span> [[Compendium|Compendium Compatible]] (where you can add repeating sections for individual items) or as one resizable free-text field to enter whatever you wish in here. You can adjust this block's behavior by going to the [[D&D 5E by Roll20#Settings Page|Settings Page]] of the sheet and going to the '''General Options'''-block to change whether this block uses the Simple or Compendium Compatible layout. <br />
<br />
When adding items to the Compendium Compatible version of this block, you have the <code>Name</code> field, a <code>Source</code>-field where you can choose between (Racial, Class, Feat, Background, or Other) , a <code>Source Type</code>-text field to describe the type, and then the multilined <code>Description</code>-textbox. Clicking on the <span style="font-family:Pictos;">y</span>(gear)-icon in the top right corner of the item will lock/unlock the item's editability. When locked down, a <span style="font-family:Pictos;">w</span>(chat bubble)-icon appears when you mouse over the feature/trait. Clicking on the <span style="font-family:Pictos;">w</span> will share this feature's description in the {{Text Chat}}.<br />
<br />
There presently isn't a means to format the raw text (italicize, bold, font alignment, etc) of the Simple version or in the Description section of either version of the Features & Traits block.<br />
<br />
You can drag-n-drop '''Feats''' from the compendium, even though they can't be selected in the Charactermancer on levelup.<br />
<br />
PC Features and Traits can be called using an ability roll:<br />
<code>%{selected|repeating_traits_$0_output}</code><br />
Simply increase the $0 value to access all Features and Traits listed on the character sheet, $1, $2, $3...<br />
<br />
<p style="clear:both;"></p><br />
<br />
==Bio Page==<br />
[[File:D&D5E-Roll20-BIO-tab.png|right|thumb|250px|The Bio Page of the PC Sheet]]The Bio page, opened by selecting "BIO" from the 4 buttons near the top right of the sheet, is comprised of free-form text fields that can be used to keep track of less "structured" information about your character. You can use this page to describe your character's appearance, keep track of who their allies are and what organizations they've worked for, and on this page is a section to supplement the inventory list, on the front page, with the "Treasure" section, where you can keep track of all the loot you find along your travels.<br />
===Bio Header===<br />
[[File:D&D5E-Roll20-Bio-header.png|550px]]<br /><br />
<br />
The header of the Bio page contains the basic run down of a character's physical appearance.<br />
*'''Character Name:''' This is carried over from every single PC Page and matches the character journal's name<br />
*'''Age:''' The character's current age<br />
*'''Size:''' The size classification for the race type (Medium for most cases)<br />
*'''Height:''' The character's height<br />
*'''Weight:''' The character's weight<br />
*'''Eyes:''' The character's eye color<br />
*'''Skin:''' The character's skin color<br />
*'''Hair:''' The character's hair color/style<br />
<br />
===Character Appearance===<br />
While the Bio Header describes the bare bone physical characteristics of a PC, this field is for fleshing out the visual peculiarities and/or cues of your character. Does you character have a piercing gaze? A stooped posture? Are they fancily dressed or are their clothes moth-eaten? In essence, this field is for everything and anything one would note about the character–from the equipment or garb they wear to how they comport themself.<br />
<br />
===Allies & Organization===<br />
This text field is for listing important or campaign relevant NPCs that the character may have a connection with. It's also for keeping track of faction allegiance. In the case of ''Dungeons & Dragons''' Forgotten Realms world, a PC could be a member of the Harpers or the Emerald Enclave, among other major factions who are all vying for power of the continent.<br />
<br />
===Character Backstory===<br />
This field is for listing your character's pre-campaign history, their relations, and the pertinent places they have been to in the past.<br />
<br />
===Additional Features & Traits===<br />
This text field is a continuation of the [[#.2817.29_Features_.26_Traits | Features & Traits]] section of the Core Page. The section on the Core Page is a good place for commonly utilized features of a character or briefly jotting down an abbreviated list. This field on the Bio page gives you more real estate to fully write down everything you need in whole.<br />
<br />
===Treasure===<br />
This text field is where you can list all the loot you've collected while searching bodies and delving through dungeons. Since much of these effects are transient and are likely to be used, given away, or sold to the highest bidder at the earliest opportunity, this may be preferable place to keep this list of items rather than adding them to the itemized Compendium Compatible Equipment section (if you have that version enabled).<br />
<br />
==Spell Page==<br />
[[File:D&D5E-Roll20-Spells-tab.png|right|thumb|400px|The Spell Page]]The Spell page, opened by selecting the "SPELLS" button from the four buttons near the top right of the sheet, is used to keep track of all of the powerful magics at your character's fingertips.<br />
<br />
===Spell Page Header===<br />
[[File:D&D5E-Roll20-Spells-header.png|550px]]On the Spells page Header you can set the ability modifier that will be used for casting spells. Selecting the Spellcasting Ability block will allow you to select an attribute from a dropdown, and this will be used in all relevant spell rolls. This attribute will be set automatically when you select a spell casting class. The next two blocks, the Save DC and Attack Bonus will be set automatically based on the class that is selected on the Core page.<br />
<br />
===Spellcasting Ability===<br />
The Spellcasting Ability modifier will automatically update, depending on the class you select on the Core page, to the correct ability modifier for your class. If, for some reason, you need to change this value you can click on the modifier listed in this section and it will give you a drop-down list of all available ability modifiers.<br />
<br />
===Spell Save DC & Attack===<br />
The Spell Save DC and Spell Attack Bonus sections cannot be changed manually, but are just a visual output of modifiers that will be happening behind the scenes. The Spell Attack Bonus is the number that will be added to all spell attack rolls, automatically.<br />
<br />
The Spell Save DC refers to the Save DC that enemies will have to beat when they are trying to dodge/resist your incoming spells. Say, Fred the Sorcerer casts Lightning bolt, and his Spell Save DC is 14. Any enemies hit by his attack will have to make a DEX save and try to beat 14. If they manage to beat the attack, then they are only grazed and take half of the damage. If they don't beat 14, then they take the full damage of the attack instead.<br />
<br />
===Spell Levels & Spells Per Day===<br />
The main section of the Spells page lists 10 sections, ranging from 0 to 9, representing the Cantrips (0) and spells level 1 - 9 where the level of the spell is listed in the triangle on the left of each section header. The number in the left square of the header represents the total number of Spell Slots, in other words, the maximum number of times a spell of this level can be cast in between long rests. This number will be set automatically depending on the level of your character, but can be modified by clicking the up or down arrow or just entering a number in the space provided. The number in the right-most box in the headers is the Slots Remaining value that can be used for you to keep track of the number of times you've cast a spell at this level.<br />
<br />
===Adding Spells===<br />
[[File:D&D5E-Roll20-Spells-Icons.png|framed|right]]<br />
When you drag spells from the <span style="font-family:Pictos;">i</span> [[Compendium]] to the sheet, a new spell entry will be added to the Spell Page under the appropriate level header. This will copy over all corresponding information linked to the spell, as well as creating an attack entry in the [[D%26D_5E_by_Roll20#.2811.29_Attacks_.26_Spellcasting|Attacks & Spellcasting]]-block on the "Core" page, if the spell can be used as an attack. The name of the spell will be listed to the left of the entry and to the right are icons for whether the spell is a Ritual (R), requires Concentration (C), and lists whether there is a Verbal (V), Somatic (S), or Material (M). There is also a circle at the far left of the entry that can be toggled to be filled in with red or left empty. This toggle represents spells that are Prepared for the day and are available for a player's convenience to help track this.<br />
<br />
You can manually add spells by selecting the <span style="font-family:Pictos;">&</span> under any of the Spell Level headings. This will present you with a blank template where you can enter all of the information about a spell. By default, the spell card only contains non-attack information about a spell. If the spell IS an attack you can change the "Output" selector from "Spellcard" to "Attack", this will show some additional input fields to fill out the attack information about the spell. Switching this input will also add an attack entry to the [[D%26D_5E_by_Roll20#.2811.29_Attacks_.26_Spellcasting|Attacks & Spellcasting]]-section on the [[#Core Page|Core page]] so this spell attack can also be cast from the main page. All of these sections are linked, so changing information in one place will also change the corresponding information in the other location. To save your edits, click on the gear icon at the upper right of the entry to collapse the spell entry.<br />
<br />
You can edit any spell at any time, by hovering your mouse over the entry to make a <span style="font-family:Pictos;">y</span> icon appear on the left. Clicking on the <span style="font-family:Pictos;">y</span> will roll out the spell once more to be edited.<br />
<br />
==Settings Page==<br />
[[File:D&D5E-by-Roll20-Settings-Page.png|thumb|right|400px|The Settings tab of the sheet, accessed from the '''<span style="font-family:Pictos;">y</span>''' icon ]]<br />
The Settings page, accessed by selecting the <span style="font-family:Pictos;">y</span>(gear) icon from the four buttons near the top right of the sheet, is where you can make changes to some parts of your character sheet that aren't represented on the other pages.<br />
<br />
===Class Options===<br />
In the class options section is where you have access to some important parts of your character, that usually are managed in the background. They are placed here so that, if needed they can be modified as well.<br />
<br />
'''Hit Dice:''' This section will be set automatically depending on the class chosen on the [[#Core Page|Core page]], but can be changed here by selecting the value and choosing a new one from the drop-down menu. This option is used whenever the "Hit Dice" section is used on the Core page.<br />
<br />
'''Carrying Capacity Modifier:''' This modifier allows you to increase the weight that a character can carry before they become encumbered.<br />
<br />
'''Global Magic Attack Modifier:''' This modifier will affect all spell attacks rolled from the sheet.<br />
<br />
'''Magic Caster Level:''' By default, a character's caster level is tethered to their class level. This option allows you to set the caster level manually, so you can have it differ from the character's class level. This will automatically change the Spell Slots Total for each spell level on the [[#Spell Page|Spells page]].<br />
<br />
'''Spell Save DC Mod:''' The Spell Save DC is normally a field you can't edit from the Spell page and is set by the character's class and level. This modifier allows you to alter that value.<br />
<br />
'''Spell Icons:''' This option will allow you to choose to turn off all the Spell Icons (R, C, V, S, & M), show them all, or only display only the ritual and concentration icons.<br />
<br />
'''Halfling Luck:''' Use this checkbox if your character is a Halfling that happens to take advantage of the Halfling Luck race feat. Using this feat will automatically re-roll any 1s rolled for attacks and skills or ability checks/saves.<br />
<br />
'''Arcane Fighter/Rogue:''' These checkboxes can be used to keep track of when your Fighter or Rogue-classed character actually has access to spells.<br />
<br />
===Multiclass Options===<br />
If you are taking advantage of the D&D 5E multiclassing you can keep track of it in this section. Any levels to your character's additional classes must be changed here, and will then be reflected in the header portion of the sheet. Once you've added additional classes in this section, any time you roll Hit Dice from the Core page it will ask you which classes hit dice you wish to use.<br />
<br />
Note: Be sure to not re-include your main class in this section, or your final level calculation will be incorrect.<br />
<br />
===Custom Class Options===<br />
If you are playing a class that is not part of the D&D 5E Compendium, you can input the important class information in this section, and checking the "Use Custom Class" checkbox will replace the main class selection with your custom built class.<br />
<br />
===Spell Slot Modifiers===<br />
This section allows you to manually modify how many spell slots your character has available for each spell level from 1 to 9.<br />
<br />
===Attribute Options===<br />
'''Attribute Modifiers:''' With this section you can manually adjust the individual Attribute Scores for Strength, Dexterity, Constitution, Intelligence, Wisdom, and Charisma.<br />
<br />
'''Initiative Modifier:''' Usually, your initiative modifier is just based off of your DEX modifier, but if you happen to find a magical item that enhances these rolls this is where you will put that bonus. This modifier will be used whenever the [[#.287.29_Armor_Class.2C_Initiative.2C_.26_Speed|Initiative]]-section is rolled on the Core page.<br />
<br />
'''Initiative Style:''' This setting allows you to select whether Initiative will be rolled with Advantage, Disadvantage, or rolled normally with a single d20 (default).<br />
<br />
'''Add DEX Tiebreaker to Initiative:''' If you would like to enable a tie breaker component to Initiative, this checkbox will enable adding your dexterity Attribute Score as a decimal value to your Initiative roll. So if you have a character with a dexterity attribute score of 14, your initiative modifier will change from a 2 to a 2.14.'<br />
<br />
'''Global Armor Class Modifier:''' This setting will modify your armor class and will be taken into account regardless of the equipment the character uses.<br />
<br />
'''Armor Class Tracking:''' There are three options available: The Automatic version that's default to the sheet where it adds 10 + your DEX modifer and then takes any armor equipped into account. A Custom version which expands out a formula upon selection where you can input your own formula for armor tracking, or you can turn Off Armor Tracking entirely. When turned off, you will need to manually adjust the Armor Class field on the Core page.<br />
<br />
===Save Options===<br />
'''Save Modifiers:''' With this section you can manually adjust the individual Save modifiers for Strength, Dexterity, Constitution, Intelligence, Wisdom, and Charisma.<br />
<br />
'''Death Save Modifier:''' A normal death save is usually just a D20 against a dc of 10, but if you're lucky enough to have a bonus to death saves, this is where you will put your bonuses. This modifier will be represented any time a "Death Save" is rolled from the Core page.<br />
<br />
'''Global Saving Throw Modifier:''' If you have an affect that would modify all saving throws, this option makes it easier to adjust your Save modifiers than having to go in and change each one individually. This modifier will be used every time any save is rolled from the sheet.<br />
<br />
===Skill Options===<br />
If your class offers the ability to achieve "Expertise" in a skill, or if you are using a Bard with the "Jack of All Trades" feat, this is where you will make these adjustments. There is also a section to add flat modifiers to any of your skills if your character has an archetype ability like Remarkable Athlete or a feat that adds a flat bonus to a skill. You can add expertise to any skill by clicking the value next to it and choosing "Expertise" from the drop-down menu. If your Bard has the Jack of All Trades feat, you can check the checkbox at the bottom of this section and it will automatically give half of your character's proficiency points to any skill check that doesn't have full proficiency.<br />
<br />
'''Passive Perception Modifier:''' This option will add a bonus to a character's Passive Perception which is not something you can change directly from the Core page of the sheet.<br />
<br />
===General Options===<br />
The General Options section has some important options that deal more with how the sheet works, rather than actual character creation. Most importantly, the NPC checkbox at the top, which will change the sheet to be the NPC version which is shaped to more easily track an NPC's information.<br />
<br />
'''Roll Queries - Always/Toggle/Query/Never Roll Advantage:''' This option will change how advantage is rolled for all attacks. It defaults to always roll advantage, which means that every time an attack is rolled it will roll twice and present the outcome of both rolls. This is useful for both advantage and disadvantage, otherwise you can just choose either the left or the right to be the default roll. Toggle adds a set of buttons at the top of the sheet to manually switch your advantage options between rolls. If Query is chosen, every time a roll is made it will ask you whether or not it's advantage. If Never is chosen, then it will always roll just a single dice per attack roll.<br />
<br />
'''Whisper Rolls to GM:''' Like above, you have the option to Never/Toggle/Query/Always whisper rolls to the GM. When this option is enabled, the attack roll will only be whispered to the GM and not made public.<br />
<br />
'''Auto Damage Roll:''' By default, damage rolls will not be rolled automatically, but only when you click the attack in the chat window. This is useful because you can choose to only roll damage when an attack hits. Using this option you can make the character always roll damage with every attack.<br />
<br />
'''Core Die Roll:''' You can change the core die (by default it is 1d20) to something else entirely here.<br />
<br />
'''Proficiency Bonus:''' By default, the character's Proficiency Bonus is calculated by class level. This setting allows you choose to calculate this bonus via By Level (the default), via a Proficiency Die as described in the Dungeon Master's Guide, or a Custom calculation which rolls out a field to enter a roll formula for the bonus.<br />
<br />
'''Global Save/Skill/Attack/Damage Modifier Field:''' This series of checkboxes will add new entries to the Saving Throws, Tools Proficiencies & Custom Skills, and Attacks & Spellcasting blocks respectively to add global modifiers (like if a character is under the effects of a Bless or Guidance spell). Each entry will have a Global label in grey at the bottom of its entry and a field to enter the modifier bonus. If you include a word in brackets with the bonus formula (ex. "1d4[Bless]"), the word enclosed in the brackets will appear when you mouse over a roll to see it's formula.<br />
<br />
'''Add Character Name to Templates:''' This option allows you to turn this on or off. When it is on, the character's name is listed in the roll template when rolls are made from the sheet. If the character sheet in question is for an NPC, you will likely want to have this off so the rolls don't accidentally show your hand of what sort of monster your party is facing. This setting is off by default.<br />
<br />
'''Auto Level Calculations:''' This option allows you to turn this on or off. When it is on, adjusting the character's class level will automatically update the character's proficiency bonus, Hit Dice, and spell Slot totals (if the class is a spellcaster).<br />
<br />
'''Encumbrance:''' This option dictates how encumbrance is handled on the Equipment block of the Core page. This requires your Inventory to be set to "Compendium Compatible" to automatically calculate and track the weight of your character's backpack if you enter the weight values for any of the items in your Equipment list. When your character becomes encumbered, and depending on its severity, the words ENCUMBERED, HEAVILY ENCUMBERED, or IMMOBILE will display in red underneath the TOTAL WEIGHT value. This setting has three options: Simple Encumbrance Rules, Variant Encumbrance Rules, or not follow Encumbrance rules at all by toggling it off from this.<br />
<br />
'''Inventory:''' With this option allows you to either have your Equipment block be "Compendium Compatible" or "Simple". The Simple version of the Equipment block will give you single text field to log your inventory. The Compendium Compatible version tracks weight, quantity, and attack options in an itemized list for every equipment item you add to the block.<br />
<br />
'''Features & Traits:''' This option can set the Features & Traits block to be either a single text field or a repeated section that will be Compendium Compatible to list traits and features in an itemized list.<br />
<br />
'''Proficiencies & Languages:''' This option can set the Proficiences & Languages block to be either a single text field or a repeated section that will be Compendium Compatible to list traits and features in an itemized list.<br />
<br />
'''Ammo Tracking (API Required):''' When using the 5th Edition OGL Companion API Script in your game (Pro Subscriber feature), you can set attacks to weapons using ammunition to automatically subtract from their tally in their Resource block. So if your character is equipped with a bow, rolling its attack will automatically remove an arrow from its Resource block.<br />
<br />
===Transition Options(outdated)===<br />
{{mbox | text = This feature doesn't seem to exist on the sheet any longer, so the info in this section is outdated}}<br />
<br />
If your campaign previously used the [https://wiki.roll20.net/DnD5e_Character_Sheet#Intro Community Contributed] or [https://wiki.roll20.net/index.php?title=DnD5e_Shaped_Character_Sheet&oldid=11112#General_Information Shaped Legacy] 5th Edition Character Sheets and you are swapping over to this one, we have an automated conversion tool that will clear or merge elements left over from those two sheets. This procedure can only be done ''once'' and can not be undone. It is recommended that you make a copy of your campaign first before attempting a sheet transition.<br />
<br />
There is also a checkbox that hides this feature entirely from the sheet. If you hide this by mistake, you can gain access to it again by creating a new character journal.<br />
<br />
=The NPC Sheet=<br />
''See Also:'' '''[[D&D5E by Roll20 NPC Attributes]]'''<br />
<br />
One of the most useful parts of the D&D 5E by Roll20 Character Sheet is that it contains both a PC sheet ''AND'' an NPC sheet. An NPC doesn't normally require the depth a PC sheet needs, so the NPC sheet is a much more slimmed down character sheet that doesn't require multiple pages like its PC counterpart. You can access this version of the sheet by going to the Settings Page, by clicking the gear icon near the top right of the sheet, and then checking the NPC checkbox. This will switch the sheet to the NPC version. You can switch back at any time by unchecking the NPC option under General Options on the new page.<br />
<br />
==NPC Options==<br />
[[File:5E_OGL_Sheet_NPC_Options.png|right|thumb|250px|The NPC Options Section]]This is the area where all of the NPC's stats will be entered, it covers everything from the NPC's name, to how strong or quick or smart it is, to what languages it speaks. Most of the fields in this section are just text fields used to keep track of information about the NPC. All of the information entered in these fields will be visible in the stat block once the NPC options are hidden. <br />
<br />
<br />
Any text that appears in light grey is placeholder text. It's there to offer you an example of what the content would be for any given field. <br />
<br />
By default, no skill or ability checks will show up in the NPC's stat block. Once you've added a value to the corresponding skill or ability save, they will appear. If for some reason the NPC will have to make a check with a skill or ability it does not have any bonus in, you can enter a 0 as the modifier for that check and it will add it to the list in the stat block below.<br />
<br />
The XP of an NPC auto-calculates based on its given challenge rating.<br />
<br />
If the NPC is a spellcaster, you can check the checkbox beside '''SPELLCASTING NPC''' and this will add a spell list section that utilizes the spell list and its functionality from the PC version of the sheet.<br />
<br />
At default, you can add Traits and Actions in their respective places after the Challenge Rating and XP area of the Stat Block. For Reactions and Legendary Actions, you need to enable them from the NPC Options section. For Reactions, check off the '''HAS REACTIONS''' checkbox. This will add a new sections to the Stat Block for you to add Reactions to. If an NPC is a monster with Legendary Actions then you must enter the number of actions that monster has access to each turn in the '''LEGENDARY ACTIONS:''' field. Once you add a number here, an additional section will appear in the stat block below, where you can add the specific legendary actions that the monster is able to do.<br />
<br />
The NPC sheet supports Compendium drag & drop. If you want to add a new monster to your game just drag the monster from the <span style="font-family:Pictos;">i</span> [[Compendium]]-tab of the [[Sidebar]] and drop it to anywhere on the Tabletop. This will automatically create a new journal entry named the same as the Compendium entry and will copy all of the information on that compendium page directly into the new sheet. If you have purchased any of the Compendium expansions that expands on the available NPCs like the Monster Manual or Volo's Guide to Monster, a token of that NPC will be added to the Tabletop that will have its stats automatically set and linked to the new journal entry.<br />
<br />
{{mbox | text = '''Note:''' If you already have a journal entry in your {{journal}}-tab with the exact same name as the <span style="font-family:Pictos;">i</span> [[Compendium]] entry, the drag and drop will not work as this automation will stop to prevent overwriting existing content the user has already created. If a drag and drop of an NPC Compendium page does not create a journal entry, run a search for that NPC's name in your Journal to see if an entry already exists. If you do not want to delete the older entry, renaming it will allow the drag and drop to work as expected.}}<br />
<br />
===General Options===<br />
Within the NPC Options section, directly below the Legendary Actions field, is the General Options that are featured on the PC Sheet: NPC checkbox, WHISPER ROLLS TO GM, and the AUTO DAMAGE ROLL options. <br />
<br />
*NPC checkbox<br />
*WHISPER ROLLS TO GM<br />
*AUTO DAMAGE ROLL<br />
*NPC NAME IN ROLLS<br />
*ADD DEX TO TIEBREAKER TO INITIATIVE<br />
<br />
Unchecking the NPC checkbox from here will revert the sheet back to the PC Sheet.<br />
<br />
===Hiding NPC Options===<br />
Once all of the desired information has been entered, you can click the <span style="font-family:Pictos;">y</span>(gear) icon at the top right to hide this section. This leaves behind just the NPC's stat block where you can make all of your rolls from. You can re-open this section to edit the information at any time by clicking on the <span style="font-family:Pictos;">y</span> icon again. It's in the same location regardless if you're looking at NPC Options or the NPC stat block.<br />
<br />
==The NPC Stat Block==<br />
[[File:5E OGL Sheet NPC v2.png|right|thumb|250px|An NPC stat block for a griffon]]Following NPC Options is the NPC Stat Block that is built off of what you input in the NPC Options section. This area may look very similar to a stat block you may find in a monster bestiary or published adventure.<br />
<br />
<br />
Any section of the stat block that has a corresponding roll will have click-able text. For example, if the NPC has to make a CON check, you can click the CON attribute to roll a CON check with all of the required modifiers automatically included. If you added a value to one of the skill modifier fields then that skill will show up in the NPC's "Saving Throws" list where you can click it to make a saving throw roll using that skill's modifier.<br />
<br />
The first section of the Stat Block mirrors all the information you added in the NPC Options section. This content is meant exclusively for rolling and can not be edited directly. You will need to change them from the NPC Options section.<br />
<br />
===Traits===<br />
Traits are pieces of information about an NPC that isn't covered by the NPC options section. These are entered directly onto the NPC's stat block. If you click the "<span style="font-family:Pictos;">&</span>" button that appears right below the "Senses/Languages/Challenge Rating" section it will add a blank entry where you can add a single trait for that NPC. Each Trait Entry features a bold title field which is then followed by a larger text box for the description of the trait. You can add any number of Traits for any NPC.<br />
<br />
===Actions===<br />
NPC actions can be used for any number of things. Each entry initially offers an Action Name field as well as a large text field for the Action description. The checkbox for ATTACK, once checked, adds more structured data fields needed for an attack roll (Type, Range/Reach, To Hit bonus, Target, Damage Roll, and Damage Type). To add a new entry you will select the <span style="font-family:Pictos;">&</span> button that appears below the Actions section. Once all of this is complete you can click the <span style="font-family:Pictos;">y</span>(gear) icon at the top of this entry to hide the input fields, leaving just the action text. You can show this information, or roll the attack, in the chat box by clicking the text for the action. If you need to make further modifications to any action you can hover over the row you wish to edit, then click on the <span style="font-family:Pictos;">y</span>(gear) icon again. This will show all of the action information input fields again. You can add any number of Actions for any NPC.<br />
<br />
===Bonus Actions===<br />
NPC bonus actions are typically not listed on the sheet, and are usually referenced in the Traits section. However, if a player wishes to use this section, it is available if the 'Bonus Action' checkbox is selected. The fields work the same as the Actions section.<br />
<br />
===Reactions===<br />
Once enabled from the NPC Options section, a new heading labeled "Reactions" and its relevant section is added to the stat block that allows you to add Reactions. These entries operate just like Traits.<br />
<br />
===Spells===<br />
Once enabled from the NPC Options section, a new heading labeled "Spells" and its relevant section is added to the stat block that allows you to add Spells. These entries will operate identically to how Spells are added and handled on the PC Sheet with the one noted exception that there is only a single column of spell entries. You can drag spells from the Compendium to add spell entries just like you would with the PC's Spell sheet. Any and all spells added to the character sheet are shared between the NPC and the PC versions.<br />
<br />
===Legendary Actions===<br />
If a number value is added to the LEGENDARY ACTIONS field in the NPC Options section, the Legendary Actions heading and section is added at the very bottom of the stat block and lists some verbiage on how many actions are available to be used on a given turn. This number is dictated by what you entered in the NPC Options. These entries operate the same way as Traits.<br />
<br />
==Rolling for Initiative for NPCs==<br />
There are two ways to roll for Initiative on the NPC sheet. You can click on the NPC's Name to roll for Initiative or you can roll from the die icon labeled INIT that is listed to the right of the Armor Class and Hit Points section of the NPC sheet, towards the top. If you have the Turn Tracker tool open, having the NPC token selected while rolling Initiative will automatically add the NPC and its initiative roll to the tracker. Creatures on the GM layer that are added to the tracker in this fashion will have their entries hidden from the players.<br />
<br />
<br />
You can also create a global Macro that will pop up as a Token Action button in the upper left hand corner of the tabletop every time a token is selected. This will allow you to roll without looking at the NPC sheet at all. The macro formula should look just like this:<br />
<br />
<code>%{selected|npc_init}</code><br />
<br />
=Advanced Use=<br />
<br />
===Custom Skills and Stats===<br />
You can set up any number of custom skills or rolls from the [[#Tool Proficiencies|Tool Proficiencies]] section just underneath the skill section on the Core tab. [[#Class & Other Resources|The Resources]] section is also useful for tracking custom stats to your campaign, game setting, or home-brew rules. There are also various options available from the Settings page to modify attributes, skills, saves, spells, and more.<br />
<br />
===Target Roll Buttons===<br />
A useful way for GMs and Players to reference their abilities is by dynamically setting up a handful of macros that can be used on a token linked to a character, rather than having to roll directly from the sheet. To do this, you'll set up a global macro from the {{Collections}}-tab. You can also write these directly in the {{Text Chat}}.<br />
<br />
In the examples, the <code>selected</code> part can be replaced with <code>target</code>, a character's name, or it's character ID.<br />
<br />
Here are some examples:<br />
<br />
'''PC'''<br />
* Attributes: <code>%{selected|strength}</code>, <code>%{selected|strength_save}</code> | Will roll the Strength Check and Strength Save for the selected [[token]](if the [[Link Token|token is linked to a sheet]])<br />
* <code>%{selected|acrobatics}</code><br />
* <code>%{selected|initiative}</code><br />
* <code>%{selected|death_save}</code><br />
* <code>%{selected|hit_dice}</code><br />
<br />
'''NPC'''<br />
* <code>%{selected|npc_init}</code><br />
* <code>%{selected|npc_str}</code><br />
* <code>%{selected|npc_stealth}</code><br />
* <code>%{selected|npc_hpformula}</code><br />
====Rolling from Repeating Sections====<br />
The example we'll be using today is setting up the 1st NPC action:<br />
<code>%{selected|repeating_npcaction_$0_npc_action}</code><br />
Now whenever you use this macro it will roll the first NPC action of whichever NPC token you have selected. You can set up a roll for each action by incrementing the 0 by 1 for each action you wish to add (I.E. <code>$1</code>, <code>$2</code>, <code>$3</code>). Here is a list of important repeating section rolls and their formulas:<br />
<br />
* Player Attack/Spell Attack <code>%{selected|repeating_attack_$0_attack}</code><br />
* Player Attack/Spell Damage <code>%{selected|repeating_attack_$0_attack_dmg}</code><br />
* Player Attack/Spell Critical Damage <code>%{selected|repeating_attack_$0_attack_crit}</code><br />
* Player Global DMG mod <code>%{selected|repeating_damagemod_$0_global_save}</code><br />
** Attr names: <code>global_damage_name</code>, <code>global_damage_damage</code>, <code>global_damage_critical_damage</code>, <code>global_damage_type</code><br />
* Proficiencies <code>%{selected|repeating_proficiencies_$0_output}</code><br />
* Tool/Custom Skill <code>%{selected|repeating_tool_$0_tool}</code><br />
* Traits/Feats: <code>%{selected|repeating_traits_$0_output}</code><br />
<br />
* Spellbook Cantrip <code>%{selected|repeating_spell-cantrip_$0_spell}</code><br />
* Spellbook Level 1 <code>%{selected|repeating_spell-1_$0_spell}</code><br />
* Spellbook Level 2 <code>%{selected|repeating_spell-2_$0_spell}</code><br />
* Spellbook Level 3 <code>%{selected|repeating_spell-3_$0_spell}</code><br />
* Spellbook Level 4 <code>%{selected|repeating_spell-4_$0_spell}</code><br />
* Spellbook Level 5 <code>%{selected|repeating_spell-5_$0_spell}</code><br />
* Spellbook Level 6 <code>%{selected|repeating_spell-6_$0_spell}</code><br />
* Spellbook Level 7 <code>%{selected|repeating_spell-7_$0_spell}</code><br />
* Spellbook Level 8 <code>%{selected|repeating_spell-8_$0_spell}</code><br />
* Spellbook Level 9 <code>%{selected|repeating_spell-9_$0_spell}</code><br />
<br />
'''NPC'''<br />
* NPC Traits/Abilities<code>%{selected|repeating_npctraits_$0_npc_roll_output}</code><br />
* NPC Actions/Attacks<code>%{selected|repeating_npcaction_$0_npc_action}</code><br />
* NPC Attack Damage<code>%{selected|repeating_npcaction_$0_npc_dmg}</code><br />
* NPC Attack Critical Damage<code>%{selected|repeating_npcaction_$0_npc_crit}</code><br />
* NPC Bonus Actions<code>%{selected|repeating_npcbonusaction_$0_npc_action}</code><br />
* NPC Legendary Actions<code>%{selected|repeating_npcaction-l_$0_npc_action}</code><br />
* NPC Mythic Actions<code>%{selected|repeating_npcaction-m_$0_npc_action}</code><br />
* NPC Spells<code>%{selected|repeating_spell-npc_$0_spell}</code><br />
<br />
===Directly Referencing Attributes===<br />
You can discover the name of most of the attributes in the sheet by hovering over them. After a couple of seconds a title will pop up and tell you how to referencing them. You can call attributes in an Ability Rolls by using <code>@{attributename}</code>. If you want to directly reference it in a roll that isn't saved on the sheet, you need to specify the character's name, or use either the <code>selected</code> or <code>target</code> key works.<br />
<br />
'''Examples:'''<br />
* <code>/em attempts to grapple and gets [[1d20+@{strength_mod}]]</code> custom [[Journal#Attributes_.26_Abilities_Tab|Ability call]], saved in the "attributes and abilities" tab of the character sheet.<br />
* <code>/r 1d20+@{Alice|strength_mod}+@{Alice|pb}</code> macro that calls a specific character<br />
* <code>/em have @{selected|hp} out of @{selected|hp|max} left.</code> macro that uses stats from a token(token must be selected before rolling)<br />
* <code>The Enemy's AC is @{target|npc_ac}</code> macro prompt the user to select a target token on the map, and uses it's stats.<br />
<br><br />
<br />
See [[Macros#Attribute_Macros]] for further general details/examples on the syntax.<br />
====PC====<br />
Here are a list of some of the more important stats:<br /><br />
<br />
'''Attributes/Saves:'''<br />
<br />
* Str: <code>strength, strength_mod, strength_save_bonus</code><br /><br />
* Dex: <code>dexterity, dexterity_mod, dexterity_save_bonus</code><br /><br />
* Con: <code>constitution, constitution_mod, constitution_save_bonus</code><br /><br />
* Int: <code>intelligence, intelligence_mod, intelligence_save_bonus</code><br /><br />
* Wis: <code>wisdom, wisdom_mod, wisdom_save_bonus</code><br /><br />
* Cha: <code>charisma, charisma_mod, charisma_save_bonus</code><br />
<br><br />
'''Skills:'''<br />
<br />
<code>athletics_bonus<br /><br />
acrobatics_bonus<br /><br />
animal_handling_bonus<br /><br />
arcana_bonus<br /><br />
deception_bonus<br /><br />
history_bonus<br /><br />
insight_bonus<br /><br />
intimidation_bonus<br /><br />
investigation_bonus<br /><br />
medicine_bonus<br /><br />
nature_bonus<br /><br />
perception_bonus, passive_wisdom<br /><br />
performance_bonus<br /><br />
persuasion_bonus<br /><br />
religion_bonus<br /><br />
sleight_of_hand_bonus<br /><br />
stealth_bonus<br /><br />
survival_bonus<br /><br />
</code><br />
<br />
'''AC, Proficiency, HD etc'''<br />
<br />
<code>pb</code>(Proficiency Bonus)<br><br />
<code>inspiration</code><br><br />
<code>ac<br /><br />
initiative_bonus<br /><br />
speed<br /><br />
hp, hp|max, hp_temp<br /><br />
hit_dice, hit_dice|max, hitdietype<br /><br />
weighttotal<br /><br />
</code><br />
<br />
'''Spells'''<br />
<br />
<code>spell_save_dc, spell_attack_bonus<br /><br />
lvl1_slots_total, lvl1_slots_expended<br /><br />
lvl2_slots_total, lvl2_slots_expended<br /><br />
lvl3_slots_total, lvl3_slots_expended<br /><br />
lvl4_slots_total, lvl4_slots_expended<br /><br />
lvl5_slots_total, lvl5_slots_expended<br /><br />
lvl6_slots_total, lvl6_slots_expended<br /><br />
lvl7_slots_total, lvl7_slots_expended<br /><br />
lvl8_slots_total, lvl8_slots_expended<br /><br />
lvl9_slots_total, lvl9_slots_expended<br /><br />
</code><br />
<br />
Spells, repeating sections:<br><br />
<code>repeating_spell-cantrip<br><br />
repeating_spell-1<br><br />
repeating_spell-2<br><br />
repeating_spell-3<br><br />
repeating_spell-4<br><br />
repeating_spell-5<br><br />
repeating_spell-6<br><br />
repeating_spell-7<br><br />
repeating_spell-8<br><br />
repeating_spell-9</code><br> <br />
<br />
Cantrip stats(most should also work for lvl.1-lvl.9):<br><br><br />
Full statname is spell level + (rowID or row number) + attribute name, e.g. <code>repeating_spell-1_$0_spellname</code> is the spell name of your first Lvl 1 spell, <code>repeating_spell-4_$1_spelldescription</code> is the description of your second lvl.4 spell.<br />
<br />
<code>spellname<br><br />
spellrange, spellcastingtime, spelltarget, spellduration<br><br />
spellschool<br><br />
spellritual<br><br />
spellconcentration<br><br />
spellcomp_v, spellcomp_s, spellcomp_m<br><br />
spellcomp_materials<br><br />
spell_ability<br><br />
spelloutput<br><br />
spellattack<br><br />
spelldamage, spelldamagetype, spelldamage2, spelldamagetype2<br><br />
spellhealing<br><br />
spelldmgmod, spell_damage_progression<br><br />
spellsave, spellsavesuccess<br><br />
spelldescription<br><br />
spellclass, spellsource</code><br />
<br />
'''Items'''<br><br />
<code>cp sp ep gp pp</code><br><br />
(copper pieces, silver, gold, electrum, platinum)<br />
<br />
<code>repeating_inventory_$#_itemcount<br><br />
repeating_inventory_$#_itemname<br><br />
repeating_inventory_$#_itemweight<br><br />
repeating_inventory_$#_equipped<br><br />
repeating_inventory_$#_useasresource<br><br />
repeating_inventory_$#_hasattack<br><br />
repeating_inventory_$#_itemproperties<br><br />
repeating_inventory_$#_itemmodifiers<br><br />
repeating_inventory_$#_itemcontent</code><br><br />
<br />
* <code>equipped</code>, <code>useasresource</code>, <code>hasattack</code> are checkboxes, with value 1 if checked.<br />
* <code>itemmodifiers</code> is for of item changes any stats, like <code>AC +2</code> adding +2 to AC when equpped.<br />
* <code>itemcontent</code> is the item description<br />
<br><br />
'''The class_resource and the other_resource'''<br><br />
<br />
<code>class_resource</code> and <code>other_resource</code> are static resources. That is to say, you need to keep in mind that they are NOT a part of the repeating section, even though it definitely looks that way on the character sheet.<br><br />
<br />
You use these to access them<br />
<br />
<code>class_resource</code><br><br />
<code>class_resource_max</code><br><br />
<code>class_resource_name</code><br><br />
<code>other_resource</code><br><br />
<code>other_resource_max</code><br><br />
<code>other_resource_name</code><br><br />
<br />
'''The repeating resources'''<br><br />
<br />
Any resources that appear beneath the "class resource" and the "other resource" are a part of the "repeating resources" section. This section is known for being confusing for beginners, so it deserves a bit of clarification.<br />
<br />
First, keep in mind that this is one section (not two sections, as people often think), and that "repeating_resource" is its section prefix.<br />
<br />
Second, keep in mind that you need to skip past the row with the "class resource" when you're figuring out the address of the row that you want to refer to. So basically, if you want to refer to the row that is directly below the row with the "class_resource", then you would add "_$0" (to form "repeating_resource_$0"). And then the next row after that is "_$1", and so on.<br />
<br />
Third, keep in mind that if you add "_resource_left" (to form "repeating_resource_$0_resource_left"), then you are specifying that you are talking about the CURRENT VALUE of the leftmost resource in that row. And if you add "_resource_left_max", then you are specifying that you are talking about the MAX VALUE of the leftmost resource in that row.<br />
<br />
Here is a complete list of all the fields that you can access in the "repeating_resource" section. Just replace the "#" character with which row you want to access.<br />
<br />
<code>repeating_resource_$#_resource_left</code><br><br />
<code>repeating_resource_$#_resource_left_max</code><br><br />
<code>repeating_resource_$#_resource_left_name</code><br><br />
<code>repeating_resource_$#_resource_right</code><br><br />
<code>repeating_resource_$#_resource_right_max</code><br><br />
<code>repeating_resource_$#_resource_right_name</code><br><br><br />
<br />
<br />
'''Features/Class Traits'''<br />
<br />
<code>repeating_traits_$0_output<br><br />
repeating_traits_$#_name<br><br />
repeating_traits_$#_source<br><br />
repeating_traits_$#_source_type<br><br />
repeating_traits_$#_description<br><br />
</code><br />
<br />
'''Other/Settings:'''<br />
<br />
<br><br />
<code><nowiki>wtype</nowiki></code> (whisper type, can have one of these values:)<br />
* <code><nowiki></nowiki></code> (empty for never whisper)<br />
* <code><nowiki>@{whispertoggle}</nowiki></code> (show the buttons on sheet that can toggle between options)<br />
* <code><nowiki>?{Whisper?|Public Roll,|Whisper Roll,/w gm }</nowiki></code><br />
* <code><nowiki>/w gm</nowiki></code> (always whisper)<br />
<br />
<br />
'''Global modifiers'''<br />
<br />
* <code>repeating_savemod_$0_global_save_roll</code><br />
* <code>repeating_skillmod_$0_global_skill_roll</code><br />
* <code>repeating_tohitmod_$0_global_attack_roll</code><br />
* <code>repeating_damagemod_$0_global_damage_damage</code><br />
<br />
====NPC====<br />
Some stats are the same as for PCs<br />
<br />
<code>npc_name<br><br />
npc_ac<br><br />
hp, hp|max<br><br />
npc_speed<br><br />
npc_challenge<br><br />
npc_xp</code><br />
<br />
Attributes: <code>strength_base, strength_mod</code> (same as PCs)<br />
Saves:<br />
<br />
<code>npc_str_save_base</code>,<code>npc_dex_save_base</code>, <code>npc_con_save_base</code>,<code>npc_int_save_base</code>,<code>npc_wis_save_base</code><code>npc_cha_save_base</code><br />
Skill bonus:<code>npc_acrobatics_base</code>, <code>npc_animal_handling_base</code> etc.<br />
<br />
Damage/Conditions stuff:<br />
<br />
<code>npc_vulnerabilities<br><br />
npc_resistances<br><br />
npc_immunities<br><br />
npc_condition_immunities</code><br />
<br />
Spells:<br />
<br />
<code>npcspellcastingflag</code> (set to "1" if caster, empty otherwise) <br />
<code>spellcasting_ability</code><br />
<code>globalmagicmod </code> (global magic attack modifier)<br />
<code>caster_level</code><br />
<code>spell_dc_mod</code> (spell save DC mod)<br />
<br />
Spells are identical to PC section<br />
<br />
Other:<br />
whisper is same as PCs<br />
<br />
<code>npc_name_flag</code> (show/hide npc name in rolls, value is either <code><nowiki>{{name=@{npc_name}}}</nowiki></code> or <code>0</code>)<br />
<br />
<br />
<sup>Note: anything with the Suffix of <code>|max</code> requires some form of Prefix, such as <code>selected|</code> making the call for such a thing look something along the lines of <code>@{selected|hp|max}</code>. The <code>|max</code> Suffix specifically calls the box on the right of the selected Attribute's Line, for example, you could fill in the Weight Total's 2nd Box with <code>@{strength}*15</code> & whenever you call <code>@{selected|weighttotal|max}</code> it will tell you your 5e standard Maximum Carry Capacity for your current Strength Score.<br />
<br />
===Custom AC Items===<br />
You can add pieces to your inventory and manually give them AC or magic bonuses that will figure into their calculations automatically. Inside the item options is a section for "MODS:". Add <code>Ac +1</code> to add an armor class bonus.<br />
<br />
===Roll Templates===<br />
''Main Article:'' '''[[D&D 5e by Roll20 Roll Templates]]'''<br />
<br />
The '''D&D5E by Roll20''' Character Sheet also includes a series of [[Roll Templates]] that you can use to dress up your own custom macros. Roll Templates provide additional layout and styling options for the display of roll results.<br />
<br />
{{ex}}<br />
[[File:5e-rolltemplate-ex1-2021.png|200px|right|none]]<br />
Rolls stealth for selected npc token, using it's stealth proficiency.<br />
<code><nowiki>/w gm &{template:npcatk} {{attack=1}} {{name=Shadow}} {{rname=Shadow Stealth}} {{rnamec=Hide}} {{r1=[[@{selected|d20}+@{selected|npc_stealth} + 6]]}} {{always=1}} {{r2=[[@{selected|d20}+@{selected|npc_stealth} + 6]]}} {{description=While in dim light or darkness, the shadow can take the Hide action as a bonus action. Its stealth bonus is **also** improved to +6 }}</nowiki></code><br />
<br />
===Magic Missile Spell===<br />
{| role="presentation" class="wikitable mw-collapsible mw-collapsed" style="float:right; margin-left: 10px;margin-right: 60px;"<br />
| Image of the Spell's settings<br />
|-<br />
| [[File:Magic-Missile-5E-2020.png|right|frame|The Magic Missile Spell]]<br />
|}<br />
<br />
RAW, Magic Missile is rolled once, and the single roll is then used for each hit. So by default the spell rolls <code>1d4+1</code>. (See [[Talk:D&D 5E by Roll20#Old Magic Missile Discussion]] for more info.)<br />
<br />
You can modify the spell to instead roll 3d4+3 at first level, and then in the ''HIGHER LVL CAST DAMAGE'' section, set it to <code>1d4+1</code>.<br />
<br />
To automatically use higher-level spell slots with Magic Missile, you have to write a 0 into the ''HIGHER LVL CAST DAMAGE'' section of the spell and select any die. It will show the box for selecting higher-level spell slots when launching Magic Missile, but since it multiplies the higher-level damage cast by 0, the added roll doesn't show up in the chat, making it roll a single die for every missile while using any level spell slot.<br />
<br />
=API=<br />
{{pro only|section}}<br />
[[API:Introduction|API Scripts]] allow for greater customization and functionality to how Roll20 operates beyond what it can do at default. This section will list some info on using various APIs that interact with the character sheet.<br />
<br />
Example of APIs from the One-Click Install menu, that designed to be used with the '''D&D 5E by Roll20''' sheet:<br />
* '''5E BattleMaster'''<br />
* '''5E Resting in Style'''<br />
* '''CashMaster'''<br />
* '''Concentration'''<br />
* '''[[Script:It's a Trap|It's a Trap! -- D&D 5E Generic]] (should detect automatically what sheet is used)<br />
** {{repo|Roll20/roll20-api-scripts/tree/master/ItsATrap_theme_5E_Generic#readme readme}}<br />
* '''ShortRest'''<br />
* '''SpellMaster'''<br />
* '''WildShape'''<br />
<br />
A good number of the more general APIs have built in settings for configuring them for usage with the 5E sheet, such as '''GroupInitiative''', '''GroupCheck''', '''Experience Tracker''', '''[[PowerCards]]''', '''[[ScriptCards]]''' (ScriptCards is an improved version of PowerCards)<br />
<br />
* '''[[GroupCheck]]:''' <code>!group-check-config --import 5E-OGL</code> will configure the API for use with this sheet<br />
* '''[[GroupInit|GroupInitiative]]:''' before use, API need to be configured for the sheet, either through the menu preset, or using the command: <code>!group-init --add-group --Bare </code><br />
* '''CombatMaster:''' is by default configured with conditions for D&D 5E<br />
* '''[[ChatSetAttr]]:''' API that can create, edit, & delete stats on sheets. Example: [[Script:ChatSetAttr#Add_new_thing_to_Repeating_Section|Adding a new magic item to a sheet]], with one chat command <br />
* '''[[Script:Ammo]]''' can be used for updating ammo & spellslots when used<br />
<br />
==Utilizing the ''5th Edition OGL by Roll20 Companion'' API Script==<br />
'''{{repo|Roll20/roll20-api-scripts/tree/master/5th%20Edition%20OGL%20by%20Roll20%20Companion 5th Edition OGL Companion}}'''is an official companion script for the "D&D 5E by Roll20" character sheet. The Companion currently supports Ammo Tracking, Automatic NPC Tokens, Automatic Death Save Tracking, and Automatic Spell Slot Tracking. <br />
<br />
{{mbox | text = Installing & creating [[API]] Scripts is a {{Pro}} feature. In order to be able to access these advanced scripts, the [[GM]] of the campaign must be a [[Pro]] subscriber and enable it for their campaign.}}<br />
<br />
<br />
'''''How to Add the API Script to your Game'''''<br />
<br />
If you have a PRO account, you can install the API script by going to your game's Campaign Page and clicking on the '''Settings''' button, and then choosing '''API Scripts'''. This brings you to the API Scripts page for your current game. The Companion Script is part of the One-Click Community API Installation options. Under the Script Library tab, there is a drop down menu that lists all the available community created scripts. Scroll down till you find the '''System Toolbox''' category and select the "5th Edition OGL by Roll20 Companion" script. The version number, the script's author, and a brief description of what the script does will appear right below the drop down menu once it is selected. Below that, click on the blue "Add Script" button to add the script to your game.<br />
<br />
<br />
'''''List of API commands for the 5th Edition OGL Companion API Script'''''<br />
* <code>!5ehelp</code> - Gives a list of the script's API commands in the chat tab.<br />
* <code>!5estatus</code> - Lists the current status of the script's features in the chat tab.<br />
* <code>!ammotracking on/off/quiet</code> - Automatically expends linked resource when attack is made<br />
* <code>!autonpctoken on/off</code> - Automatically generates a NPC token on the GM's screen based on the default token when an NPC's health calculation is rolled<br />
* <code>!deathsavetracking on/off/quiet</code> - Automatically ticks off successes and failures when death saves are rolled, clearing on death, stabilization, or hp recovery<br />
* <code>!longrest <character name></code> - This will add Hit Dice recover and if spelltracking is on, this command will reset all of the character's spell slots to unspent.<br />
* <code>!npchp <character name></code> - Rolls NPC hit point totals using their formula and updates the token bar. If no character name is provided it will roll the selected tokens.<br />
* <code>!spelltracking on/off/quiet</code> - Automatically expends spell charges as cast, factoring in higher level casting, and spells marked as Rituals will not spend a spell slot.<br />
<br />
<br />
Options:<br />
* ''on'' - Toggles the functionality on (default)<br />
* ''off'' - Disables the functionality<br />
* ''quiet'' - Maintains functionality while preventing results from being output to the chat.<br />
<br />
<br />
===Automatic Ammunition Tracking===<br />
''Main Article:'' '''[[D&D 5E by Roll20: How to setup Ammunition and Resource tracker]]'''<br />
<br />
Automatic Ammunition Track is a feature that requires the above Companion API Script. Once installed, follow these instructions to enable automatic ammunition tracking in your game:<br />
<br />
This example sets up a Longbow with a quiver of Arrows to track.<br />
# On the Settings (Gear Icon) tab of a character sheet, under GENERAL OPTIONS, make sure that the INVENTORY option is set to "Compendium Compatible" and not "Simple".<br />
# While still under GENERAL OPTIONS, set the AMMO TRACKING feature to ON.<br />
# Create manually or drag a missile weapon (ex. Longbow) from the Compendium to your sheet.<br />
# Create manually or drag a missile type (Arrows) from the compendium to your sheet<br />
# Expand the missile type (Arrows) by clicking on the "I" information icon that appears when hovering the mouse over the item.<br />
# Select the USE AS RESOURCE checkbox. (ammunition items dragged from the Compendium will have this option automatically checked off)<br />
# On the CORE tab, expand the missile weapon (Long Bow) in the ATTACKS & SPELLCASTING section by clicking on the gear icon that appears when hovering over the attack.<br />
# In the AMMUNITION section put the exact name of the ammunition resource (Arrows). If you want to spend more than one piece of ammunition per shot you want to add the number of pieces after the name of the ammunition resource and a comma. (ex. ''Arrows,2'' )<br />
<br />
<br />
Now, any time the missile weapon (Longbow) is rolled, a piece of ammunition will automatically be spent and the chat will make note. Additionally after the first time the missile weapon is used the AMMUNITION section will update with the ID of the resource repeating section, this is normal and expected.<br />
<br />
<br />
===Automatic Spell Slot Tracking===<br />
<br />
Automatic Spell Slot Tracking is a feature that requires the above Companion API Script. Once installed, follow these instructions to enable automatic spell slot tracking in your game:<br />
* In the chat input area of the Sidebar, type ''!5estatus'' and press Enter, to check if spelltracking is set to 'on'.<br />
* If not, type ''!spelltracking on'' and press Enter to activate this feature.<br />
* Alternatively, you may type ''!spelltracking quiet'' and press Enter to activate this feature, while preventing spelltracking messages from being displayed in the chat.<br />
<br />
<br />
<br />
Once the Spell Slot Tracking has been activated, each time a spell is cast:<br />
# The number of cast spells of the appropriate level is updated in the Spell tab of the character sheet (see [[5th Edition OGL by Roll20|Spell Levels & Spells Per Day]]).<br />
# A message is output in the chat, displaying the spell level, the number of available spell slots and the number of used spell slots for this level.<br />
# Spell slots decrement as spells are cast. <br />
# Spells that are marked as a Ritual do not affect the tally of spell slots when cast.<br />
<br />
<br />
At any time, you can manually adjust this count directly in the Spell Page of the character sheet.<br />
<br />
=Updates=<br />
* {{hc|articles/360037772613-Change-Log Roll20 Changelog}} - Full Changelog of Roll20, updates for 5E sheet are included<br />
* {{fpl|10096810/ D&D 5th Edition by Roll20 (Q2Y2021)}} often has mentions of latest updates<br />
* Major Sheet Updates:<br />
** Feats can now be selected in Charactermancer {{fpl|8891809 June 2020}}<br />
** Game [[creator]] can select which [[compendiums]] are or aren't accessible in a game. [https://app.roll20.net/forum/post/8738570/release-note-for-may-26-2020 May 26 2020]<br />
<br />
=Known Issues=<br />
The sheet has a number of known bugs and issues, some which are mentioned in the sheet's latest forum thread.<br />
<br />
'''Charactermancer/Character Creation'''<br />
* '''Charactermancer & Compendium drag-n-drop doesn't work when sheet is in a separate window.''' This is [[Character_Sheets#Character_Sheet_in_a_separate_window|an inherit limitation to how character sheets work]] at the moment. <br />
* '''Multiclassing & spell selection''' - There are troubles when multiclassing spellcasters and getting to select spells from the right lists.<br />
* '''Duplicate races/classes from Essential Kit appear in selection''' You need to uncheck EK from your compendium for it to no longer appear in selections.<br />
<br />
<br />
'''General:'''<br />
* '''Warlock spell slots''' - The Warlock's spell slots don't work too well with the sheet, and most people use some manual adjustments for how they work. The number of spell slots also appears wrong in the Charactermancer.<br />
* '''NPC stat <code>desc</code> changed into <code>description</code>''' This was a recent update that broke some macros for people, resulting in error messages along: "can't find ''desc'' attribute" {{fpl|8297517/ release notes march 2020}}<br />
<br />
=Sheet Guides=<br />
* [[5E Macros]]<br />
* {{blog|638339117446578176/tome-of-tips-dungeons-dragons-5th-edition-ogl Tome Of Tips: The D&D 5E character sheet}}<br />
* {{yt.be|9BGGr97qJdY|Learning Roll20: EP01 Character Sheets (D&D 5E)}} 50min, by Roll20 (2020)<br />
<br />
=Related Pages=<br />
* D&D 5E by Roll20 sheet<br />
** [[D&D5E by Roll20 NPC Attributes]]<br />
** [[D&D 5e by Roll20 Roll Templates]]<br />
** [[D&D 5E by Roll20: How to setup Ammunition and Resource tracker]]<br />
* [[5E]] - general D&D 5E info for Roll20. Lists also the alterantive character sheets for 5E<br />
* [[D&D]] - Roll20 stuff on the various editions.<br />
* {{Compendium}}<br />
** [[Compendium Sharing]]<br />
* [[Character Vault]]<br />
<br />
=See Also=<br />
* {{repo|Roll20/roll20-character-sheets/tree/master/DD5thEditionLegacy Sheet sourcecode}} - (Public version of sheet code is 1½+ years behind from what is actually used)<br />
* {{hc|articles/360037772613-Change-Log Roll20 Changelog}} - Full Changelog of Roll20, updates for 5E sheet are included<br />
<br /><br />
<br /><br />
[[Category:Character Sheet Documentation]]<br />
[[Category:Official Sheet]]<br />
[[Category:DnD5E]]<br />
[[Category:Featured articles]]</div>5004103https://wiki.roll20.net/D%26D_5E_by_Roll20D&D 5E by Roll202021-10-11T12:45:13Z<p>5004103: /* API */</p>
<hr />
<div>{{revdate}}{{HCbox|{{hc|360037773573-5th-Edition-OGL-by-Roll20 D&D 5E by Roll20}} }}<br />
[[File:5E OGL Sheet Core v2.6.png|500px|thumb|right|The '''D&D 5E by Roll20''' Character Sheet]]<br />
<br />
This is the community-driven documentation for the '''[[5E|D&D 5E]] by Roll20''' character sheet. Previously the sheet was known as the '''"5th Edition OGL Sheet"''' or just the '''"OGL Sheet"'''.<br />
<br />
=The Basics=<br />
This page is a ''[[Community Wiki]]'' guide to the Official D&D 5th Edition character sheet, which is updated with info tricks that might not be covered by the {{hc|articles/360037773573-5th-Edition-OGL-by-Roll20 official sheet documentation}}.<br />
<br />
<br />
To find out about the latest updates, issues and talk about the sheet, check the {{fpl|10096810/ D&D 5th Edition by Roll20 (Q2Y2021)}}-thread on the {{forum|category/277980 forums}}.<br />
<br />
<br />
[[Bug|Bug reports]] for the sheet is best reported in the same thread. If you find bugs in the 5E Compendium or 5E marketplace content, {{bug}}.<br />
<br />
<br />
__TOC__<br />
<br />
==Adding the Character Sheet to a Game==<br />
[[File:D&D5E-Roll20-sheet-selection.png|300px|thumb|right|The Sheet Selection Menu]]An official or community contributed character sheet [[Add_character_sheet#Adding_a_Character_Sheet_to_your_Campaign|can be added to any game when you first create it]]. On the Game Creation screen, underneath the large blue '''“I’m Ready, Create Game!”''' button, is the '''“Optional: Choose a Character Sheet”''' section. Located here is a drop down menu that lists all the character sheets built either by Roll20 officially or created by the community. These sheets are sorted under their respective RPG Systems in alphanumerical order. Once selected, a preview of the character sheet will load upon the creation page for you to review as well as showcase relevant information about the sheet, such as the sheet’s creator and its key features.<br />
<br />
<br />
The '''D&D 5E by Roll20''' Sheet can be found under either: '''Sheets by Roll20''' → D&D 5E by Roll20 OR '''Dungeons and Dragons 5E''' → D&D 5E by Roll20<br />
<br />
<br />
If you want to add a character sheet to an existing campaign, you can find this drop down menu once again by accessing the [[Game Settings Page]] from the [[Game_Management#Game_Details_Page|Game Details]]-page.<br />
<br />
{{mbox | text = '''NOTE:''' If you have added custom attributes to your character journals prior to adding a character sheet to a campaign, you may want to delete them first. Adding a character sheet to a campaign will create its own set of custom attributes on all of your character journals, but it will reuse any attributes encountered if they share the same name. This can cause calculation issues on the sheet.}}<br />
<br />
<br />
If you were previously using either the [[DnD5e Shaped Character Sheet|D&D 5E (Shaped)]] or [[DnD5E_Community_Contributed|D&D 5E (Community Contributed)]] sheets and wish to transfer over to the '''D&D 5E by Roll20''' version, it's a good idea to ask help on the [https://app.roll20.net/forum/category/277980 forums].<br />
<br />
<div style="clear: both"></div><br />
<br />
==Where to Find the Sheet==<br />
Once a character sheet has been added to a game, and once inside it, on all [[Journal#Characters|Characters Journals]], a new tab will be available between the '''“Bio & Info”''' and '''“Attributes & Abilities”''' tab labelled '''“Character Sheet”'''. Much like the Attributes & Abilities tab, only players who have been granted Edit permissions for the journal entry will be able to access the Character Sheet tab.<br />
<br />
''See also:'' '''[[Add_character_sheet#Adding_New_Characters_In-Game|Create new character sheets to your players]]'''<br />
<br />
==Sheet Features==<br />
The '''D&D 5E by Roll20''' sheet has all of the functionality of a pen and paper character sheet, and much more. Certain aspects of the sheet have been streamlined or automated to remove bookkeeping and speed up gameplay. The key features are auto-calculations, [[Macro|macro]] buttons, and [[D&D 5e by Roll20 Roll Templates|roll templates]]. The sheet defaults to using the rules as printed in the D&D 5E SRD, however it's dynamic enough to allow you and your group to use many custom house rules you might want.<br />
<br />
===Auto Calculations===<br />
Many parts of the sheet use auto calculations to fill in derived attributes with the expectation that you're using the rules as printed in the 5th Edition SRD. Many of these calculated traits can be modified from the character sheet's <span style="font-family:Pictos;">y</span> [[D&D 5E by Roll20#Settings Page|Settings]]-tab, and those set by Sheet Workers can be edited directly. Below are some examples of Sheet Worker and Auto Calculation functionality:<br />
<br />
* '''Class''' - Changing the character's class from the header will automatically update the character's saving throw proficiencies, their hit die type, spell casting ability, and spell save DC. <br />
* '''Level''' - Changing the character's level will also update their proficiency bonus, number of spells per day, and more.<br />
* '''Attributes''' - Changing one of the character's attributes will also update the related modifier, skills that are based on that attribute, and derived stats such as initiative or passive perception.<br />
<br />
===Roll Buttons and Roll Templates===<br />
[[File:5E_OGL_Sheet_Rollable_Buttons.gif|right|frame|Any label that highlights in red when the mouse hovers over it is rollable.]]<br />
''Main Page:'' '''[[D&D 5e by Roll20 Roll Templates|D&D 5E by Roll20 Roll templates]]'''<br />
<br />
Most of the stats in the game can be rolled by hovering over their name, the stat will turn red, and then left-clicking the mouse. This is true for Attributes, Saves, Skills, Hit Dice, Death Saves, Tool Proficiencies, Attacks & Spellcasting, Spell Cards, and NPC Actions/Attacks. Any of these roll buttons can be dragged directly from the sheet to your [[Macro Quick Bar]], enabled from the <span style="font-family:Pictos;">y</span> [[My Settings]]-tab of Roll20's [[Sidebar]].<br />
<br />
Player characters have both a simple and attack [[D&D 5e by Roll20 Roll Templates|roll template]] that is output to the {{Text Chat}}-tab on the right hand [[Sidebar]]. The simple template is used for everything except for attacks. The attack template is shaped to show up in three pieces; the attack at the top, information in the middle, and damage at the bottom. Depending on your sheet settings, the damage will not roll automatically unless you click on the name of the attack from the roll template in the chat tab. This was designed to simulate the tabletop experience of rolling to attack and then rolling damage if necessary. You can change this behavior in the sheet <span style="font-family:Pictos;">y</span> [[D&D 5E by Roll20#Settings Page|Settings]]-tab, tab under "Auto Damage Roll".<br />
<br />
<div style="clear: both"></div><br />
<br />
====Rolling for Advantage and Disadvantage====<br />
With the '''D&D 5E by Roll20''' Sheet, the [[D&D 5E by Roll20#Settings Page|default sheet settings]] has Advantage set to ''always'' rolled for convenience purposes. It is commonly agreed upon that a gaming group uses the left roll result when advantage is not being used for a check. When advantage or disadvantage is in play, simply choose the higher or lower result among the two per usual. You can change this behavior in the sheet <span style="font-family:Pictos;">y</span> [[D&D 5E by Roll20#Settings Page|Settings]]-tab (gear icon at the top right of the page), tab under "Roll Queries". You have the choice of "Always Roll Advantage" (the default setting), "Advantage Toggle", "Query Advantage", or "Never Roll Advantage".<br />
<br />
'''Advantage Toggle:''' The Advantage Toggle will add three buttons to the top of your character sheet: "Advantage", "Normal", and "Disadvantage". You can click on any of these to roll for Advantage (the highest roll result will highlight in black), Disadvantage (the lowest roll result will highlight in black), or a single d20.<br />
<br />
'''Query Advantage:''' The Query Advantage setting will prompt a dialog box to appear whenever you roll from your sheet. It will ask you to select what sort of roll want to do (Normal, Advantage, Disadvantage). After choosing the type you want, the roll will occur in chat.<br />
<br />
'''Never Roll Advantage:''' When rolling from your sheet, only a single d20 will be rolled.<br />
<br />
===Resizable Text Fields===<br />
[[File:5E_OGL_Sheet_Resizable_Text_Fields.gif|right|frame|Making a text field larger is just a matter of click and dragging.]]There are many free-text fields on the sheet that give you a place to keep information that doesn't necessarily follow a specific format. All of the fields on the Bio Tab are free-text fields as well as the Description fields present for attacks, spells, equipment, features & traits, and NPC actions. If your text overflows past the bottom of a text field, you can resize it to view the content in its entirety by clicking and dragging the bottom right corner icon shown in the adjoining image.<br />
<br />
<br />
At present, these fields can only contain raw text. There are no formatting options (bold, italic, etc.) available.<br />
<br />
<div style="clear: both"></div><br />
<br />
===The Padlock Button and Organizing Elements===<br />
(aka. '''[[Character_Sheets#Repeating_Section|Repeating Section]]''')<br />
[[File:5E_OGL_Sheet_Padlock.gif|right|frame|The Padlock Toggle]]There is a <span style="font-family:Pictos;">(</span> (padlock) icon set at the bottom of several different fields of the '''D&D 5E by Roll20''' Sheet. It is used where a player is meant to add entries such as individual attacks, actions, pieces of equipment, features & traits, tool proficiences & custom skills, other proficiencies & languages, and spells. This icon behaves as a toggle button. <br />
<br />
When set in the <span style="font-family:Pictos;">(</span> locked position (default), a player can add new entries into the field. When the button is toggled to <span style="font-family:Pictos;">)</span>(unlocked), a player can no longer add new entries, but they will be able to reorder or delete any of the existing ones. The <span style="font-family:Pictos;">#</span>(red trash bin)-icon overlaid on the right hand side of the entry will delete it.<br />
<br />
{{Ambox<br />
|nocat=true<br />
| type = content<br />
| text = '''Deleting an entry cannot be undone!''' On left side of every entry while the padlock is <span style="font-family:Pictos;">)</span> unlocked is a re-sort icon symbolized by '''<big>≡</big>'''(three parallel lines). By clicking and dragging on this icon, you can rearrange the order of the entries in the field.<br />
}}<br />
<br />
{{Ambox<br />
|nocat=true<br />
| type = content<br />
| text = Some of the features of '''Repeating Sections''' do not work when the [[Character_Sheets#Character_Sheet_in_a_separate_window|Character Sheet is in a separate window]].<br />
}}<br />
<br />
<br />
<div style="clear: both"></div><br />
<br />
==Utilizing the 5th Edition SRD Compendium==<br />
[[File:5E_OGL_Sheet_Compendium.png|right|The Compendium Tab]]Upon adding the D&D 5E by Roll20 Character Sheet to a campaign, the [https://app.roll20.net/compendium/dnd5e/BookIndex| 5th Edition SRD Compendium] is automatically enabled for use from it's own <span style="font-family:Pictos;">i</span> [[Compendium]]-tab in the '''[[Sidebar]]''' of the application. It's located between the {{Journal}} and <span style="font-family:Pictos Custom;">u</span> [[Jukebox]]-tabs, and is accessible for both GM and Player alike.<br />
<br />
<br />
The <span style="font-family:Pictos;">i</span> [[Compendium]] allows for rapid searching of all rules, classes, monsters, spells, items, and more that are included in the 5th Edition SRD. This minimizes time spent for the gaming group to leaf through a book in the middle of a session for a rule clarification. Even better, both the GM and the Player can utilize dragging and dropping* from the <span style="font-family:Pictos;">i</span> [[Compendium]]-tab directly to your character sheets. This makes statting NPCs and PCs far faster than inputing everything manually.<br />
<br />
{{mbox | text = '''NOTE:''' The 5th Edition SRD is similar but NOT identical to the ''Dungeons and Dragons'' 5th Edition Rule Book. Some skills, classes, creatures, items, and other elements found within the ''Dungeons and Dragons'' rule book are strictly intellectual property of Wizards of the Coast and not accessible through their Open-Game License(OGL).}}<br />
<br />
<br />
===Statting PCs===<br />
Dragging from the <span style="font-family:Pictos;">i</span> [[Compendium]] works for the Equipment and Spell fields of the PC Sheet. This will not only carry over the name of the item or spell, but the relevant attack and damage rolls and any rules or flavor text that comes with it. Adding Compendium items in this fashion also automatically adds the equipment item (if it's a weapon) or spell to the Attacks & Spellcasting field to roll directly from. Items that modify a character's Attributes, Saves, AC, To Hit, Damage, Spell Attacks, and Spell DC will be automatically calculated on the sheet when dragged in. For example, if a Belt of Giant Strength is dragged to a sheet, the strength Attribute Score will become highlighted in blue and its attribute score will be increased. An asterisk is appended to the right of the score to also signify that it has been modified by an item. When you mouse over this number, the strength Attribute Score will revert back to what its unmodified total so you can refer back to it. Dropping a Compendium items that is an ammunition type (arrows, crossbow bolts, blowgun darts, etc) will automatically fill out a resource field for that item and link it to its entry in the Equipment section.<br />
<br />
To insert a Compendium item into the character sheet, run a search for the Item or Spell you want to add in the <span style="font-family:Pictos;">i</span> [[Compendium]]-tab. Once found, click and drag on the Compendium item's name so that it creates a little named tile that follows along with your mouse. Drag this over to the character sheet, it doesn't matter where. A text box that reads, "ACCEPTING DROP FROM COMPENDIUM" will appear on your sheet if this is done correctly. Let go of the tile and the entry will be auto-completed with all the data pertaining to the the Compendium entry in the correct location on the sheet. You can see this in action below under [[#Equipment|Equipment]].<br />
<br />
===Statting NPCs===<br />
You can fill out an entire NPC sheet in a single drag and drop. Run a search for the NPC you want to create from the <span style="font-family:Pictos;">i</span> [[Compendium]]-tab. Once found, click and drag on the NPC name so that it creates a little named tile that follows along with your mouse. Drag this to anywhere over the Tabletop area of the screen. Let go of the tile and a new character journal will be created named after the NPC from the Compendium entry. Its sheet will be changed over to the NPC sheet and filled with the entire NPC entry from the Compendium including their Actions, Reactions, and Legendary Actions if applicable. If you're using one of the Compendium expansions bought from the Roll20 Marketplace like the Monster Manual or Volo's Guide to Monsters, token art will also be pulled from the Compendium entry, placed on the table, and linked to your NPC's journal.<br />
<br />
You can also drag an NPC entry from the Compendium to an existing journal entry if you have the sheet open. If the sheet is in PC sheet mode, it will automatically change it over to the NPC sheet, and add its entry elements to it.<br />
<br />
One thing to note about dragging a stat block over from the Compendium is that it uses an ''additive'' behavior. It will not replace anything that you have already entered manually.<br />
<br />
=The PC Sheet=<br />
The '''D&D 5E by Roll20 Sheet''' contains both the PC Sheet ''and'' the NPC Sheet. By default, a new character journal is set to the PC sheet, but you can switch between the two by toggling it from the [[#Settings Page|General Options Settings]]. The PC Sheet is split up into four pages and can be selected from the buttons just underneath the header at the top of the sheet. They are listed from left to right order: The [[#Core Page|Core Page]], The [[#Bio Page|Bio Page]], The [[#Spells Page|Spells Page]], and The [[#Setting Page|Setting Page]].<br />
<br />
== Creating and Leveling up a character with Charactermancer ==<br />
Players and GMs using the '''D&D 5E by Roll20''' Sheet can use the Charactermancer to create and level up characters.<br />
<br />
'''How to use the Charactermancer for [[Charactermancer (D&D Fifth Edition)|character creation and leveling]].'''<br />
<br />
<br />
{{Ambox<br />
|nocat=true<br />
| type = content<br />
| text = The Charactermancer do not work when the [[Character_Sheets#Character_Sheet_in_a_separate_window|Character Sheet is in a separate window]].<br />
}}<br />
<br />
==Core Page==<br />
[[File:5E_OGL_PC_Core_Guide.jpg|right|frame|The Core Page]]The Core Page is selected by default and has most of the information you'll want to use on a regular basis to play your character. This should look very similar to the content you would normally find on the first sheet of the physical "D&D 5E by Roll20" player character sheet. The screenshot at the top of this wiki page displays the entirety of the Core Page. <br />
===(1) Core Header===<br />
[[File:D&D5E-Roll20-core-header.png|550px]]<br />
<br />
The header block at the top of the sheet changes based on the page you have selected. On the Core page you can select a class by its dropdown menu. The available options from the dropdown are: Barbarian, Bard, Cleric, Druid, Fighter, Monk, Paladin, Ranger, Rogue, Sorcerer, Warlock, and Wizard. You can create a custom class from the Settings Page.<br />
<br />
Once a class has been selected you can update the class's level by changing the number next to the class. The sheet will also automatically mark the abilities that class has proficiency in as well as automatically select the dice that will be used when Hit Dice are rolled. You can change the Hit Dice setting manually from the options menu. If your character multi-classes, then the secondary class and its level will appear beside the primary class. This Class and Level field can hold up to four classes if desired.<br />
<br />
The fields for Background, Race, Alignment, and Experience Points allow you to fill in whatever text you wish to put in them. The Character Name persists over all pages of the sheet and is tied to the name you give to the journal entry. Changing it on the sheet itself will also change the name on the character journal and vice versa once it is closed.<br />
<br />
===(2) Attributes===<br />
<br />
[[File:5E_OGL_Sheet_Attribute_Block.jpg|left]]Along the left side of the sheet are listed the 6 primary attributes: Strength, Dexterity, Constitution, Intelligence, Wisdom, and Charisma. These attributes are used by almost every other calculation on the sheet, as they are the core definition of a character. Each attribute block has the core attribute score, which can be changed by modifying the number in the oval at the bottom of each block, and, inside the square, the attribute modifier which is auto-calculated based on the score below it. All racial ability score increases must be manually added to the core attribute score using the settings "gear" symbol at the top of the page (where the Core, Bio, and Spells buttons are located.) The attribute modifier uses the following calculation to set the value:<br />
<br />
<br />
<code>[[floor((@{strength}-10)/2)]]</code><br />
<br />
The attribute can be referenced by its name, such as @{dexterity} while the attributes modifier can be referenced by adding the mod suffix, @{dexterity_mod}.<br />
<br />
<div style="clear: both"></div><br />
<br />
===(3) Inspiration===<br />
<br />
[[File:D&D5E-Roll20-inspiration.png|left]]You can track whether or not you have Inspiration by clicking the circle next to the Inspiration block at the top left of the Core page. This will toggle a dragon spiral icon on and off for indication purposes.<br />
<br />
<div style="clear: both"></div><br />
<br />
===(4) Proficiency Bonus===<br />
<br />
[[File:5E_OGL_Sheet_Proficiency.png|left]]Your character's proficiency bonus is listed near the top left of the page. You cannot modify this value manually, instead it is automatically set based off your character's over-all level. Your character's Level can be set by changing the number next to your Class name in the [[#header_info|Header]] at the top when on the Core page.<br />
<br />
<div style="clear: both"></div><br />
<br />
===(5) Saving Throws===<br />
<br />
[[File:5E_OGL_Sheet_Saving_Throws.png|left]]Next to the core Attributes on the left side of the page is a list of the same attributes to be used in making saving throws. To mark an attribute that your character has proficiency in for saving throws, check the box next to the appropriate attributes. When you select a class in the header section of the Core page it will automatically check the correct boxes for that class's proficiencies.<br />
<br />
You can add an additional field to Saving Throws to serve as a Global Save Modifier. An example is if the character is under the influence of the Bless spell and can roll a 1d4 in addition to the result of their saving throws. This is enabled from the Settings Page under General Options. Once enabled a seventh checkbox and field will be added at the bottom of the Saving Throws block with a text field to enter the additional die roll. For this example, you could enter "1d4[BLESS]" in the global checkbox's text field that you can enable when the character is under the effects of the Bless spell. The word between the brackets becomes a label that can be seen when you mouse over the roll result in chat. While this Global Save Modifier is checked, every roll made from the Saving Throws block and performing a Death Save will add this modifier to the result.<br />
<br />
<div style="clear: both"></div><br />
<br />
===(6) Skills===<br />
[[File:5E_OGL_Sheet_Skills.png|left]]<br />
To the right of the Core Attributes is a list of all of the character's Skills. Each skill can be rolled by clicking on the skill name. If you have proficiency in a specific skill, then you would check the box next to the skill name, this will automatically add your proficiency bonus to that skill's checks. Each skill also lists the core attribute, that is used in the roll calculations, next to it in parenthesis.<br />
<br />
You can set advanced skill options for the Settings page, such as skill expertise, flat bonuses from class archetypes or feats, as well as Jack of All Trades.<br />
<br />
<div style="clear: both"></div><br />
<br />
===(7) Armor Class, Initiative, & Speed===<br />
<br />
[[File:D&D5E-Roll20-AC-Init-Speed.png|left]]The Armor Class & Speed blocks at the top center of the page can be used to keep track of your Armor and Speed values. The Initiative block cannot be modified manually, but instead is auto-calculated based off your character's Dexterity. If you have any additional initiative modifiers you can add them on the {{gear}} [[#Settings Page|Settings Page]] under Initiative Modifier in the Class Options block.<br />
<br />
Armor Class can also be tracked automatically by using the [https://app.roll20.net/compendium/dnd5e/BookIndex Compendium] compatible inventory, on by default.<br />
<br />
You can configure a custom AC calculation using the {{gear}} [[#Settings Page|Settings Page]] under the Attribute Tracking section. It's listed as "Armor Class Tracking" and is set to "Automatic" by default. If you select Custom, you can select up to two different attributes to apply to the character's armor class.<br />
<div style="clear: both"></div><br />
<br />
====Using the Global AC Modifiers====<br />
If you check the "Show Global AC Modifier" field in the character sheet General Options settings, the sheet will display a repeating section to configure and apply different modifiers to AC. So, for example, if your character has a common bonus, such as from a spell or a conditional feat or fighting style, you can toggle that AC bonus from the character sheet directly.<br />
<br />
====Rolling for Initiative and the Turn Order Tracker====<br />
Clicking on the word INITIATIVE will roll that character's initiative score. If your players have [[Token|tokens]] linked to their character sheets, they can roll their initiative ''and'' simultaneously add their character and its initiative score to the {{Turn Tracker}} automatically. What is required of the player is that their linked token must be currently selected on the Tabletop before they roll off their sheet.<br />
<br />
If you would like to enable a tie breaker component to Initiative, there is an option to enable this from the [[#Settings Page|Settings Page]] under the "Attribute Options" block. What this does is that it will add your dexterity Attribute Score as a decimal value to your Initiative. So if you have a character with a dexterity attribute score of 14, your initiative modifier will change from a <code>2</code> to a <code>2.14</code>.<br />
<br />
===(8) Hit Points & Temporary Hit Points===<br />
[[File:5E_OGL_Sheet_HP.png|left]]The Current Hit Points and Temporary Hit Points blocks are used to keep track of your character's Hit Points (HP). Inside the Current Hit Points block, at the top, is a line that lists the character's maximum amount of HP. <br />
<br />
<br />
When your character takes damage, if they have any, it should be subtracted from their Temporary Hit Points first, then any remaining damage would then come off of the character's Current Hit Points.<br />
<br />
<div style="clear: both"></div><br />
<br />
===(9) Hit Dice===<br />
[[File:5E_OGL_Sheet_Hit_Dice2.png|left]] The Hit Dice block is used to keep track of and roll your character's hit dice. Inside the Hit Dice block, at the top, is a line to keep track of the total number of dice your character can have. In the main area of the block you would keep track of the remaining hit dice. Clicking the "HIT DICE" label will roll the hit dice for your selected class automatically. If you wish to change the dice that is rolled you can do so in the Class Options section of the [[#Settings Page|Settings Page]] ({{gear}} icon). <br />
<br />
<br />
If your character is multi-classed, when rolling your hit dice (by clicking "''HIT DICE''", a pop-up will ask which of your character's current class's hit dice you want to roll. This input accepts only numerals a input to make automatic tracking of the [[API:A Guide to the API|API]] possible.<br />
<div style="clear: both"></div><br />
<br />
===(10) Death Saves===<br />
[[File:5E_OGL_Sheet_Death_Saves.png|left]]The Death Saves block is used to keep track of your character's death save rolls once they have been knocked out. You can click the "DEATH SAVES" label to make a death save roll. If you roll greater than 10 you would check one of the boxes next to "Successes" otherwise you would check a box next to "Failures". If your character has any modifiers to their death save rolls they can be added in the Class Options section of the Settings Page(gear icon).<br />
<div style="clear: both"></div><br />
<br />
===(11) Attacks & Spellcasting===<br />
[[File:5E_OGL_Sheet_Attacks_And_Spellcasting.png|left]]The Attacks & Spellcasting block in the center of the Core page of this character sheet will be one of the most often used sections. To start, you can manually add any attack or spell to this section by hovering over the block and clicking the "Add" button(the <span style="font-family:Pictos;">&</span> symbol). This will open a form that can be filled out with all of the information about the specific attack or spell you are adding. <br />
<br />
<br />
This section will automatically add attacks, with all the stats, for spells that have an attack component when they are added to your spell sheet on the [[#Spells Page|Spells Page]]. This happen both if you add the spell manually or if you drag and drop a spell from the <span style="font-family:Pictos;">i</span> [[Compendium]]. An attack is also automatically created if you drag and drop an item from the Compendium into your sheet.<br />
<br />
<div style="clear: both"></div><br />
[[File:Poisoned Dagger 5e Attack.png|right|frame|An example of an attack form filled out for a physical attack using a +1 Poisoned Dagger]]For example, lets say Erin the Bold has a +1 Poisoned Dagger that has the stats of a regular dagger, but also metes out an additional 1d6 of poison damage alongside the typical 1d4 points of piercing damage. The image displayed to the right is how the attack would be set up:<br />
<br />
<br />
Since this is a [https://app.roll20.net/compendium/dnd5e/Items:Dagger#h-Dagger dagger], and daggers have the "[https://app.roll20.net/compendium/dnd5e/Weapons#h-Weapons Finesse]" attribute I can chose either STR or DEX for my bonus attribute. Erin is quicker than she is strong, so we will pick DEX as the attribute to attack with, as well as checking the "proficient" checkbox since Erin is experienced with using these sorts of weapons. She doesn't have any other gear that might make her attacks better, so we will leave the generic bonus between the attribute and proficiency blank, or 0. Being a +1 Poisoned Dagger means that it is also magical, so it gets a 1 in the magic bonus slot just below. A dagger can also be used as a thrown weapon, so we've added the weapon's throwing range info to the "Range" field. Since a weapon does damage, we have checked the first "Damage" checkbox and filled in the required fields. This dagger does 1d4 piercing damage + Erin's DEX mod + 0 bonus damage (this would be used for bonus damage on top of the magical +1) and it doesn't have anything to change the critical damage so we just put the same damage into the "crit" box. Because this dagger can also cause poison damage, we also check the second "Damage" checkbox and fill in the info for the 2nd set of damage. The poison does a flat 1d6 poison with no extra bonuses, so we've selected "-" to say there is no attribute that adds to this damage. This damage also doesn't have anything to make the crit different so we set that to 1d6 as well. There are no extra saving throws or effects that are included with this attack, so we leave these additional sections blank. <br />
<br />
These additional effect sections will be used more commonly with spells, like [https://app.roll20.net/compendium/dnd5e/Fireball#h-Fireball Fireball], where you would require a DEX save against your SPELL DC, which will be set according to your character's spell casting level. For a fireball, the save effect would be "half damage" and the "Description" would be something like "Hits all creatures within 20 ft of the explosion point".<br />
<br />
After you are done modifying all of individual stats for an attack you can click the gear icon at the top right of that section and it will hide the stats for that attack. If ever you need to change these stats in the future you can hover over the entry and click the <span style="font-family:Pictos;">y</span>(gear)-icon that shows up to unhide the stats section. <br />
<br />
<div style="clear: both"></div><br />
====Adding Global Attack and Damage Modifier====<br />
You can add two special entries to the Attacks & Spellcasting block to handle to global Attacks and Damage modifications to rolls. An example is if the character is under the influence of the Bless spell and can roll a 1d4 in addition to the result of their attack roll. This is enabled from the [[#Settings Page|Settings Page]] under General Options. Once enabled, a checkbox will be added at the bottom of the Attacks & Spellcasting block with a text field to enter the additional die roll. For this example, you could enter <nowiki>"1d4[BLESS]"</nowiki> in the global checkbox's text field that you can enable when the character is under the effects of the Bless spell. The word between the brackets becomes a label that can be seen when you mouse over the roll result in chat. While these Global Modifiers are checked, every roll made from the Attacks & Spellcasting block will add these modifiers to the result.<br />
<br />
====Rolling from the Attacks & Spellcasting Block====<br />
[[File:Poisoned Dagger 5e Roll.png|frame|An attack roll from a +1 Poisoned Dagger]]Rolling from the Attacks & Spellcasting Block is no different than rolling from any other portions of the character sheet. Hovering your mouse over any entry here will highlight its entire label (NAME, ATK, and DAMAGE/TYPE) in red and you'll be able to click on it to roll the attack or spell. You can also drag this entry into the Macro Bar to give yourself easy access to this attack. Because this is a repeating section, the macro name will be a bit messy, but you can right-click the button and rename the macro to whatever you like.<br />
<br />
With any attack that checks for AC, you will see TWO rolls set side by side for the Armor Class check with the name of the attack listed underneath them with the Attack modifier bonus (ATK) appended to the Attack name in light grey. The Roll20 D&D 5E Character Sheet ''always'' rolls for Advantage by default, so you will always have two roll results for this check (most gaming groups use the left roll result if neither Advantage or Disadvantage is being factored in the check). If there is a specified range for the attack, this will be listed above the attack's name.<br />
<br />
Underneath the AC Check and Attack Name is the Damage roll result for the attack. Underneath this roll result will be the Damage Type (ex. slashing, piercing, poison, fire, etc.) listed in light grey italicized font.<br />
<br />
For spells that don't check for AC and instead require a Saving Throws to mitigate or negate the spell's effect, the SPELL DC is listed first. Underneath this, in italicized font, is the effect if a character succeeds the check listed. Underneath the effect is the required attribute saving throw that must be rolled. If Damage is applied, this result is rolled and listed next with its Damage Type.<br />
<br />
[[File:5e_attack_example.gif|right|frame|How to view attack damage when the sheet is set to "Don't Auto Roll Damage"]]<br /><br />
<br />
<br />
{{mbox | text = '''NOTE:''' If your character sheet's Settings have "Auto Damage Roll" set to "Don't Auto Roll Damage" under General Options, the damage will not be listed underneath the AC roll result in chat. The damage was rolled, but presently hidden from view. Anyone can see the damage delivered by manually unfolding the roll result open by hovering your mouse over the roll result in chat and clicking on the attack/spell's name.}}<br />
<div style="clear: both"></div><br />
<br />
===(12) Personality Traits, Ideals, Bonds, and Flaws===<br />
These text fields lock to prevent accidental edits. When a sheet is first created, these fields are unlocked and given a dashed yellow border to the top of the field to showcase that they're editable. To lock the field after entering text, click on the gear icon in the upper right corner of the field. This will remove the yellow border and the field will conform in height to display everything within it.<br />
<br />
There presently isn't a means to format the raw text (italicize, bold, font alignment, etc) within these fields and any line breaks are stripped out. If you ever need to edit the content again while the field is locked, mouse over the desired field and the gear icon will reappear in the top right. Clicking on that will unlock the field once again for edits.<br />
<br />
===(13) Class & Other Resources===<br />
[[File:5E_OGL_Sheet_Resources.png]]<br />
<br />
The Class & Other Resource Blocks can be used to keep track of either an item quantity you have in your equipment (like arrows in a quiver), or skills that don't fit into the other sections on the sheet (like a '''Sorcerer's Sorcery Points''', a '''Cleric's Channel Divinity''' at higher levels, or the number of rounds a '''Barbarian''' has been '''Raging''' so far in a combat encounter).<br />
<br />
There are 3 fields per Block:<br />
* Resource Max:<br />
** The Resource Max field is a text box which allows you to quantify exactly what you're tracking (ex. "Total: 10 Rounds").<br />
* Resource:<br />
** The Resource field is a numeral that you dial up or down or input directly.<br />
* Resource Name:<br />
** The Resource Name is a text box that allows you to label the resource when you click on the light grey "OTHER RESOURCE" label to overwrite it with your own.<br />
**"OTHER RESOURCE" is placeholder text<br />
<br />
<br />
A resource block will be filled automatically if you checkmark an Equipment item as "USE AS A RESOURCE" & the Item Quantity field will be paired with the Resource field in the Resource block & vice versa (you'll need to click outside of the field or hit Enter for changes to refresh across the sheet). If the two resource blocks given by default are not enough then you can add additional blocks by hovering over the section & clicking the "Add" (+ symbol) button.<br />
<br />
The Item Name will also be added to the Resource Name field, however the Resource Max field is apparently not linked to the Item currently.<br />
<br />
If you drag & drop an ammunition item type from the Compendium into your character sheet, the item is added to the Equipment block & is automatically listed & linked as an Other Resource.<br />
<div style="clear: both"></div><br />
To call the first set of class resources use:<br />
* Class Resource <code>@{class_resource}</code><br />
* Other Resource <code>@{other_resource}</code><br />
<br />
<br />
To call the Repeating resources use<br />
* Repeating Resource 1st left<code>@{repeating_resource_$0_resource_left}</code><br />
* Repeating Resource 1st right<code>@{repeating_resource_$0_resource_right}</code><br />
* Repeating Resource 2nd left<code>@{repeating_resource_$1_resource_left}</code><br />
* Repeating Resource 2nd right<code>@{repeating_resource_$1_resource_right}</code><br />
* etc.<br />
<br />
<br />
If you want to do a basic Full Readout of the Repeating Resource, the Format would be (Top Left to Bottom Right):<br />
* Class: <code>@{class_resource_name}: @{class_resource} / @{class_resource|max}</code><br />
* Other: <code>@{other_resource_name}: @{other_resource} / @{other_resource|max}</code><br />
* Left 0: <code>@{repeating_resource_$0_resource_left_name}: @{repeating_resource_$0_resource_left} / @{repeating_resource_$0_resource_left|max}</code><br />
* Right 0: <code>@{repeating_resource_$0_resource_right_name}: @{repeating_resource_$0_resource_right} / @{repeating_resource_$0_resource_right|max}</code><br />
* Left 1: <code>@{repeating_resource_$1_resource_left_name}: @{repeating_resource_$1_resource_left} / @{repeating_resource_$1_resource_left|max}</code><br />
* Right 1: <code>@{repeating_resource_$1_resource_right_name}: @{repeating_resource_$1_resource_right} / @{repeating_resource_$1_resource_right|max}</code><br />
* etc.<br />
<br />
===(14) Tool Proficiencies===<br />
[[File:5E_OGL_Sheet_Tool_Proficiencies.png|left]]The Tool Proficiencies block is for listing a character's Tool Proficiency skills. At the bottom of this block is an "Add" (<span style="font-family:Pictos;">&</span> symbol) button. Clicking this will add a new entry to this block where you can add all of the relative stats for a specific tool proficiency, say Woodcarver's Tools. You can set the level of proficiency to either Proficient, Expertise, or Jack of All Trades. The roll bonus for that tool will reflect the proficiency level selected. Next is an Attribute drop down menu where you can select which character attribute to roll with for a proficiency check. One of the options you can choose is "QUERY ATTRIBUTE" which when you click on the Tool Proficiency to roll it, you will be prompted to choose which attribute you would like to use. The attribute used for the check will be up to the GM when it is time to make the roll check. If there is any additional bonus modifiers that come along with the tool in question, you can input it in the "MODS:" field.<br />
<br />
Once you finished filling out the stats for this tool you can click the <span style="font-family:Pictos;">y</span>(gear) icon at the top right of the entry to hide the stat fields and leaving behind just the rollable button. You can roll by either clicking on this rollable button or dragging it to your [[Macro Bar]].<br />
<br />
You can also use this section to create custom skills or rolls for your campaign setting or home-brew ruleset. Check out the [[#Custom Skills and Stats|Advanced Use]] section for further details.<br />
<br />
====Global Skill Modifier====<br />
You can add a special entry to the Tool Proficiencies & Custom Skills block to handle to global Attacks and Damage modifications to rolls. An example is if the character is under the influence of the Guidance spell and can roll a 1d4 in addition to the result of their skill check. This feature is enabled from the [[#Settings Page|Settings Page]] under General Options. Once enabled, a checkbox will be added at the bottom of the Tool Proficiences & Custom Skills block with a text field to enter the additional die roll.<br />
<br />
For this example, you could enter "1d4[Guidance]" in the global checkbox's text field that you can enable when the character is under the effects of the Guidance spell. The word between the brackets becomes a label that can be seen when you mouse over the roll result in chat. While this Global Modifier is checked, every roll made from the Tool Proficiencies & Custom Skills block and the Skills block will add this modifier to the result.<br />
<div style="clear: both"></div><br />
<br />
===(15) Other Proficiencies & Languages===<br />
[[File:5E OGL Sheet Proficiencies.png|left]]<br />
This block can be set up to be Compendium Compatible (where you can add repeating sections for individual items) or as one resizable free-text field to enter whatever you wish in here. If you don't feel the Tool Proficiency block is needed (as in, you don't feel like your party will ever have to roll individual tool sets), you can store a character's Tool Proficiencies here instead. There presently isn't a means to format the raw text (italicize, bold, font alignment, etc). You can adjust this block's behavior by going to the Settings Page of the sheet and going to the General Options block to change whether this block uses the Simple or Compendium Compatible layout.<br />
<br />
When the Other Proficiences & Languages block is made Compendium Compatible, each repeating field lists a Type selection field and a Proficiency text field. Type has the following options available from its drop down selection menu: Language, Weapon, Armor, Other. <br />
<p style="clear:both;"></p><br />
<br />
===(16) Equipment===<br />
[[File:5E OGL Sheet Equipment.png|framed|right|The Equipment block of the PC Sheet]]<br />
The Equipment block at the bottom of the page has 2 different versions: a Simple version that features a single plain text field where you can track all of your equipment in any format you wish and a Compendium Compatible version that allows you to drag and drop items from the Compendium to automatically populate repeated sections for each indivdual piece of equipment.<br />
<br />
To swap between the two different Equipment block versions, first, go to the sheet's Settings Page (gear icon at the top right of the page) and then to the "General Options" section. Here, on the field labeled "Inventory", you can select between "Simple" or "Compendium Compatible" respectively. Like the name implies, if you want to be able to copy items directly from the Compendium using drag and drop, you must use the Compendium Compatible version. Dragging item entries from the Compendium to the character sheet will add it fully filled in the Equipment section as well as other automated actions described below.<br />
<br />
====Automated Compendium Functionality====<br />
If you populate the Equipment block by dragging and dropping <span style="font-family:Pictos;">i</span> [[Compendium]] items, there are several automatic features that occur when the entries you drag in our equipment items.<br />
Auto-Equip: Every item dragged to the sheet is automatically equipped in the Equipment Section<br />
*'''Weapons:''' A weapon dragged in from the Compendium will add an attack in the Attacks and Spellcasting section for that item.<br />
*'''Armor:''' Armor that is dragged in from the Compendium will add its bonus to the Armor Class (while equipped) section. If you drag multiple pieces of armor to the same sheet and at least two armor entries are equipped at once, a warning will pop up in red at the top of the Equipment Block that the Armor Class isn't being correctly calculated because of the bonus overlap. This warning will dissapear when you unequip down to a single set of armor.<br />
*'''Magical/Wondrous Items:''' Items that modify Attributes, Saves, AC, To Hit, Damage, Spell Attacks, and Spell DC will add that bonus to those elements on the sheet. In most cases, the attribute that is being modified will highlight in blue and followed with an asterisk to showcase that the attribute is being modified by an item. Mousing over the modified number will display the base value of that attribute before the item's modification is applied. This stat modification only applies if the item is equipped in the Equipment section and it will remove its bonus if it is unequipped.<br />
*'''Ammunition:''' Items dragged in from the Compendium that are used for ammunition such as arrows, bolts, darts, and slingstones, will automatically populate and link to an Other Resource field.<br />
<br />
====Manually Adding Items====<br />
You can also add items manually by hovering over the block and clicking the "Add" button (+ symbol). Each equipment entry, by default, show fields for quantity, name, and weight of an item. If you hover over a row and click the small "information" icon (grey-filled circle with a lowercase i centered in it) that appears at the bottom right of the entry you can also set some additional features. <br />
<br />
*'''Equipped Checkbox:''' The checkbox changes the appearance of the Item Name so it's easier to tell what your character currently has equipped from a glance. When left unchecked, the Item Name's font turns grey. When checked, the Item Name becomes a solid black.<br />
*Use As A Resource Checkbox: When checked, this will enable one of the Class Resource blocks and list the item name and its quantity within it. The quantity is tied between the two so changing it in one will be reflected in the other field after clicking outside the field.<br />
*'''PROP:''' This is a text field where you would take note of weapon properties such as ''finesse'', ''versatile'', or ''light''.<br />
*'''MODS:''' This is a text field where you would take note if an item (likely magical) would modify your stats in some fashion such as a character's Attributes, Saves, Skills, AC, To Hit, Damage, Spell Attacks, and Spell DC. If a stat is modified here, its attribute value will become highlighted in blue and adjusted by the supplied modifier listed here. An asterisk is appended to the right of the value to also signify that it has been modified by an item. While your mouse is hovering over the attribute, it will revert back to its unmodified total so you can refer back to its pre-moddified value.<br />
**The format for a stat modification is ''stat name:n'' where n is the stat bonus (ex. ''Strength:21'')<br />
*'''Description Field:''' This is a simple text field to include a description of the particular item and of any special qualities or effects it might have on the player.<br />
Some if not all of these fields will be filled in automatically when adding from the Compendium (where applicable).<br />
<br />
Both versions of the equipment field have the sections for each of the [https://app.roll20.net/compendium/dnd5e/Treasure#h-Treasure coins] you may find on your adventures: copper(CP), silver(SP), electrum(EP), gold(GP), and platinum(PP).<br />
<br />
====Encumbrance====<br />
If you are following Encumbrance rules, the <span style="font-family:Pictos;">i</span> [[Compendium|Compendium Compatible]] Equipment block will automatically calculate and track the weight of your character's backpack if you enter the weight values for any of the items in your Equipment list. When your character becomes encumbered, and depending on its severity, the words ENCUMBERED, HEAVILY ENCUMBERED, or IMMOBILE will display in red underneath the TOTAL WEIGHT value. You can also choose to follow Simple, Variant Encumbrance rules, or not follow Encumbrance rules at all by toggling it off on the [[D&D 5E by Roll20#Settings Page|Settings Page]] under "General Options".<br />
<br />
====Mods====<br />
The Mods field of each piece of equipment can modify the values of ability scores, AC, saving throws, Skill (Ability) checks and more. What follows is a list of the modifiers, and the proper syntax for adding them.<br />
<br />
All modifiers are separated by commas. There are other modifiers that can appear the mod field, used in creating the item from a compendium drag and drop operation, but the modifiers below have live effects on the character sheet, depending on if the item is marked as “equipped”.<br />
<br />
'''replace the <code>+n</code>, with the number you want.''' For example, if you want to boost Animal Handling skill by 3, you look at the table and find <code>Animal Handling +n</code>, so you will add to your item <code>Animal Handling +3</code>.<br />
<br />
{| class="wikitable" <br />
|-<br />
! Modifier<br /><br />
! Effect<br /><br />
|-<br />
| style="width: 20%;" | '''Combat Modifiers'''<br />
| '''These affect items that provide attacks (Appear in the attack section of the character sheet)'''<br />
|-<br />
| Melee Attacks +n<br />
| Adds +n hit "Magic Bonus" to that attack. It is not global, and only affects a weapon(melee or ranged), not an item, staff or other category. The bonus is figured into the attacks display on the 5e sheet.<br />It is NOT ''Melee Attack''.<br />
|-<br />
| Melee Damage +n<br />
| Adds +n damage "Magic Bonus" to that attack. It is not global, and only affects a weapon(melee or ranged), not an item, staff or other category. The bonus is listed separately in the attacks display on the 5e sheet.<br />
|-<br />
| Spell Attack +n<br />
| Adds a global +n to the character's Spell Attack bonus.<br />It is NOT ''Spell Attacks.''<br />
|-<br />
| '''Saving Throws'''<br />
| '''All modifiers stack with “Saving Throws +n'''<br />
|-<br />
| Strength Save +n,<br />Dexterity Save +n,<br />Constitution Save +n,<br />Intelligence Save +n,<br />Wisdom Save +n,<br />Charisma Save +n<br />
| Adds a +n to the indicated saving throw<br />''Do not use a colon.''<br />
|-<br />
| Saving Throws +n<br />
| Adds a Global Modifier to ALL saving throws.<br />
|-<br />
| Spell DC +n<br />
| Adds a global +n to a spell casting character’s Spell Save DC.<br />It is NOT Spell ''Save'' DC.<br />
|-<br />
| '''Ability Scores'''<br />
| <br />
|-<br />
| Strength +n,<br />Dexterity +n,<br />Constitution +n,<br />Intelligence +n,<br />Wisdom +n,<br />Charisma +n<br />
| Provides a bonus to the indicated ability score, which will appear in blue on the sheet while the bonus is active.<br />Do not use a colon. ''Strength: +10'' will do nothing<br />
|-<br />
| Strength n,<br />Dexterity n,<br />Constitution n,<br />Intelligence n,<br />Wisdom n,<br />Charisma n<br />
| Replaces the indicated ability score, which will appear in blue on the sheet while the bonus is active.<br />Do not use a colon. ''Strength: 10'' will do nothing<br />
|-<br />
| '''Skills'''<br />
| <br />
|-<br />
| Acrobatics +n,<br />Animal Handling +n,<br />Arcana +n,<br />Athletics +n,<br />Deception +n,<br />History +n,<br />Insight +n,<br />Intimidation +n,<br />Investigation +n,<br />Medicine +n,<br />Nature +n,<br />Perception +n,<br />Performance +n,<br />Persuasion +n,<br />Religion +n,<br />Sleight of Hand +n,<br />Stealth +n,<br />Survival +n<br />
| Adds the value to the indicated Skill roll. Note that in this case, the <code>+</code> and a colon are optional. <code>Acrobatics +5</code>, <code>Acrobatics 5</code>, <code>Acrobatics: +5</code>, <code>Acrobatics: 5</code> will all add <code>5</code> to the character’s Skill roll. For consistency and to guard against future functionality, it’s probably best to follow the format for ability scores, and use a plus sign with no comma: <code>Acrobatics +5</code>.<br />There is no Global Skill modifier<br />
|-<br />
| '''AC'''<br />
| <br />
|-<br />
| AC +n<br />
| By itself, <code>AC: 13</code> adds 13 to the character’s Armor Class. It does not replace it. <br /><br />If <code>Shield</code>, <code>Light Armor</code>, <code>Medium Armor</code>, or <code>Heavy Armor</code> is also in the mods field, it will change the calculation.<br />''<code>Light Armor, AC: 13</code>'' will give a formula of 13 + dex mod<br />''<code>Medium Armor, AC: 13</code>'' will give a formula of 13 + dex mod (max +2)<br />''<code>Heavy Armor, AC: 13</code>'' will give you flat AC 13<br />''Shield, AC: 13'' would add 13 to the your AC. The Shield keyword is superfluous in this case.<br />''<code>Shield, AC: 2</code>'' will just add 2 to the AC.<br />Finally, a bare modifier, such as for a Ring of Protection can just be written as <code>AC: +2</code> or <code>AC +1</code>.<br /><br />Shield or bare AC bonuses will stack with other armor mods on different items. You cannot equip multiple armors simultaneously, or have a custom armor equation on the settings tab and wear an armor. This will generate a flag.<br /><br />The + and a colon are semi-optional. <code>AC +5</code>, <code>AC: +5</code>, <code>AC: 5</code> will all work. However, <code>AC 5</code> will do nothing. For consistency and to guard against future functionality, it’s probably best to indicate a base AC as <code>AC: n</code> and a Shield as <code>AC +n</code>.<br />At this point, there is no way to differentiate between Ranged AC and Melee AC, though some magic items such as the ''Arrow Catching Shield'' make the distinction.<br />
|}<br />
<br />
<br />
<br />
<div style="clear: both"></div><br />
<br />
===(17) Features & Traits===<br />
[[File:5E OGL Sheet Features Traits.png|thumbnail|left|The Compendium Compatible itemized version of the Features & Traits section]]<br />
The '''Features and Traits '''-block is the place to store '''Class-''', '''Race-''' and '''Background Features''', '''Feats''', and other special notes about your character or of a certain piece of equipment or ability. When using the Charactermancer, the previously mentioned features appears in this section.<br />
<br />
This block can be set up to be <span style="font-family:Pictos;">i</span> [[Compendium|Compendium Compatible]] (where you can add repeating sections for individual items) or as one resizable free-text field to enter whatever you wish in here. You can adjust this block's behavior by going to the [[D&D 5E by Roll20#Settings Page|Settings Page]] of the sheet and going to the '''General Options'''-block to change whether this block uses the Simple or Compendium Compatible layout. <br />
<br />
When adding items to the Compendium Compatible version of this block, you have the <code>Name</code> field, a <code>Source</code>-field where you can choose between (Racial, Class, Feat, Background, or Other) , a <code>Source Type</code>-text field to describe the type, and then the multilined <code>Description</code>-textbox. Clicking on the <span style="font-family:Pictos;">y</span>(gear)-icon in the top right corner of the item will lock/unlock the item's editability. When locked down, a <span style="font-family:Pictos;">w</span>(chat bubble)-icon appears when you mouse over the feature/trait. Clicking on the <span style="font-family:Pictos;">w</span> will share this feature's description in the {{Text Chat}}.<br />
<br />
There presently isn't a means to format the raw text (italicize, bold, font alignment, etc) of the Simple version or in the Description section of either version of the Features & Traits block.<br />
<br />
You can drag-n-drop '''Feats''' from the compendium, even though they can't be selected in the Charactermancer on levelup.<br />
<br />
PC Features and Traits can be called using an ability roll:<br />
<code>%{selected|repeating_traits_$0_output}</code><br />
Simply increase the $0 value to access all Features and Traits listed on the character sheet, $1, $2, $3...<br />
<br />
<p style="clear:both;"></p><br />
<br />
==Bio Page==<br />
[[File:D&D5E-Roll20-BIO-tab.png|right|thumb|250px|The Bio Page of the PC Sheet]]The Bio page, opened by selecting "BIO" from the 4 buttons near the top right of the sheet, is comprised of free-form text fields that can be used to keep track of less "structured" information about your character. You can use this page to describe your character's appearance, keep track of who their allies are and what organizations they've worked for, and on this page is a section to supplement the inventory list, on the front page, with the "Treasure" section, where you can keep track of all the loot you find along your travels.<br />
===Bio Header===<br />
[[File:D&D5E-Roll20-Bio-header.png|550px]]<br /><br />
<br />
The header of the Bio page contains the basic run down of a character's physical appearance.<br />
*'''Character Name:''' This is carried over from every single PC Page and matches the character journal's name<br />
*'''Age:''' The character's current age<br />
*'''Size:''' The size classification for the race type (Medium for most cases)<br />
*'''Height:''' The character's height<br />
*'''Weight:''' The character's weight<br />
*'''Eyes:''' The character's eye color<br />
*'''Skin:''' The character's skin color<br />
*'''Hair:''' The character's hair color/style<br />
<br />
===Character Appearance===<br />
While the Bio Header describes the bare bone physical characteristics of a PC, this field is for fleshing out the visual peculiarities and/or cues of your character. Does you character have a piercing gaze? A stooped posture? Are they fancily dressed or are their clothes moth-eaten? In essence, this field is for everything and anything one would note about the character–from the equipment or garb they wear to how they comport themself.<br />
<br />
===Allies & Organization===<br />
This text field is for listing important or campaign relevant NPCs that the character may have a connection with. It's also for keeping track of faction allegiance. In the case of ''Dungeons & Dragons''' Forgotten Realms world, a PC could be a member of the Harpers or the Emerald Enclave, among other major factions who are all vying for power of the continent.<br />
<br />
===Character Backstory===<br />
This field is for listing your character's pre-campaign history, their relations, and the pertinent places they have been to in the past.<br />
<br />
===Additional Features & Traits===<br />
This text field is a continuation of the [[#.2817.29_Features_.26_Traits | Features & Traits]] section of the Core Page. The section on the Core Page is a good place for commonly utilized features of a character or briefly jotting down an abbreviated list. This field on the Bio page gives you more real estate to fully write down everything you need in whole.<br />
<br />
===Treasure===<br />
This text field is where you can list all the loot you've collected while searching bodies and delving through dungeons. Since much of these effects are transient and are likely to be used, given away, or sold to the highest bidder at the earliest opportunity, this may be preferable place to keep this list of items rather than adding them to the itemized Compendium Compatible Equipment section (if you have that version enabled).<br />
<br />
==Spell Page==<br />
[[File:D&D5E-Roll20-Spells-tab.png|right|thumb|400px|The Spell Page]]The Spell page, opened by selecting the "SPELLS" button from the four buttons near the top right of the sheet, is used to keep track of all of the powerful magics at your character's fingertips.<br />
<br />
===Spell Page Header===<br />
[[File:D&D5E-Roll20-Spells-header.png|550px]]On the Spells page Header you can set the ability modifier that will be used for casting spells. Selecting the Spellcasting Ability block will allow you to select an attribute from a dropdown, and this will be used in all relevant spell rolls. This attribute will be set automatically when you select a spell casting class. The next two blocks, the Save DC and Attack Bonus will be set automatically based on the class that is selected on the Core page.<br />
<br />
===Spellcasting Ability===<br />
The Spellcasting Ability modifier will automatically update, depending on the class you select on the Core page, to the correct ability modifier for your class. If, for some reason, you need to change this value you can click on the modifier listed in this section and it will give you a drop-down list of all available ability modifiers.<br />
<br />
===Spell Save DC & Attack===<br />
The Spell Save DC and Spell Attack Bonus sections cannot be changed manually, but are just a visual output of modifiers that will be happening behind the scenes. The Spell Attack Bonus is the number that will be added to all spell attack rolls, automatically.<br />
<br />
The Spell Save DC refers to the Save DC that enemies will have to beat when they are trying to dodge/resist your incoming spells. Say, Fred the Sorcerer casts Lightning bolt, and his Spell Save DC is 14. Any enemies hit by his attack will have to make a DEX save and try to beat 14. If they manage to beat the attack, then they are only grazed and take half of the damage. If they don't beat 14, then they take the full damage of the attack instead.<br />
<br />
===Spell Levels & Spells Per Day===<br />
The main section of the Spells page lists 10 sections, ranging from 0 to 9, representing the Cantrips (0) and spells level 1 - 9 where the level of the spell is listed in the triangle on the left of each section header. The number in the left square of the header represents the total number of Spell Slots, in other words, the maximum number of times a spell of this level can be cast in between long rests. This number will be set automatically depending on the level of your character, but can be modified by clicking the up or down arrow or just entering a number in the space provided. The number in the right-most box in the headers is the Slots Remaining value that can be used for you to keep track of the number of times you've cast a spell at this level.<br />
<br />
===Adding Spells===<br />
[[File:D&D5E-Roll20-Spells-Icons.png|framed|right]]<br />
When you drag spells from the <span style="font-family:Pictos;">i</span> [[Compendium]] to the sheet, a new spell entry will be added to the Spell Page under the appropriate level header. This will copy over all corresponding information linked to the spell, as well as creating an attack entry in the [[D%26D_5E_by_Roll20#.2811.29_Attacks_.26_Spellcasting|Attacks & Spellcasting]]-block on the "Core" page, if the spell can be used as an attack. The name of the spell will be listed to the left of the entry and to the right are icons for whether the spell is a Ritual (R), requires Concentration (C), and lists whether there is a Verbal (V), Somatic (S), or Material (M). There is also a circle at the far left of the entry that can be toggled to be filled in with red or left empty. This toggle represents spells that are Prepared for the day and are available for a player's convenience to help track this.<br />
<br />
You can manually add spells by selecting the <span style="font-family:Pictos;">&</span> under any of the Spell Level headings. This will present you with a blank template where you can enter all of the information about a spell. By default, the spell card only contains non-attack information about a spell. If the spell IS an attack you can change the "Output" selector from "Spellcard" to "Attack", this will show some additional input fields to fill out the attack information about the spell. Switching this input will also add an attack entry to the [[D%26D_5E_by_Roll20#.2811.29_Attacks_.26_Spellcasting|Attacks & Spellcasting]]-section on the [[#Core Page|Core page]] so this spell attack can also be cast from the main page. All of these sections are linked, so changing information in one place will also change the corresponding information in the other location. To save your edits, click on the gear icon at the upper right of the entry to collapse the spell entry.<br />
<br />
You can edit any spell at any time, by hovering your mouse over the entry to make a <span style="font-family:Pictos;">y</span> icon appear on the left. Clicking on the <span style="font-family:Pictos;">y</span> will roll out the spell once more to be edited.<br />
<br />
==Settings Page==<br />
[[File:D&D5E-by-Roll20-Settings-Page.png|thumb|right|400px|The Settings tab of the sheet, accessed from the '''<span style="font-family:Pictos;">y</span>''' icon ]]<br />
The Settings page, accessed by selecting the <span style="font-family:Pictos;">y</span>(gear) icon from the four buttons near the top right of the sheet, is where you can make changes to some parts of your character sheet that aren't represented on the other pages.<br />
<br />
===Class Options===<br />
In the class options section is where you have access to some important parts of your character, that usually are managed in the background. They are placed here so that, if needed they can be modified as well.<br />
<br />
'''Hit Dice:''' This section will be set automatically depending on the class chosen on the [[#Core Page|Core page]], but can be changed here by selecting the value and choosing a new one from the drop-down menu. This option is used whenever the "Hit Dice" section is used on the Core page.<br />
<br />
'''Carrying Capacity Modifier:''' This modifier allows you to increase the weight that a character can carry before they become encumbered.<br />
<br />
'''Global Magic Attack Modifier:''' This modifier will affect all spell attacks rolled from the sheet.<br />
<br />
'''Magic Caster Level:''' By default, a character's caster level is tethered to their class level. This option allows you to set the caster level manually, so you can have it differ from the character's class level. This will automatically change the Spell Slots Total for each spell level on the [[#Spell Page|Spells page]].<br />
<br />
'''Spell Save DC Mod:''' The Spell Save DC is normally a field you can't edit from the Spell page and is set by the character's class and level. This modifier allows you to alter that value.<br />
<br />
'''Spell Icons:''' This option will allow you to choose to turn off all the Spell Icons (R, C, V, S, & M), show them all, or only display only the ritual and concentration icons.<br />
<br />
'''Halfling Luck:''' Use this checkbox if your character is a Halfling that happens to take advantage of the Halfling Luck race feat. Using this feat will automatically re-roll any 1s rolled for attacks and skills or ability checks/saves.<br />
<br />
'''Arcane Fighter/Rogue:''' These checkboxes can be used to keep track of when your Fighter or Rogue-classed character actually has access to spells.<br />
<br />
===Multiclass Options===<br />
If you are taking advantage of the D&D 5E multiclassing you can keep track of it in this section. Any levels to your character's additional classes must be changed here, and will then be reflected in the header portion of the sheet. Once you've added additional classes in this section, any time you roll Hit Dice from the Core page it will ask you which classes hit dice you wish to use.<br />
<br />
Note: Be sure to not re-include your main class in this section, or your final level calculation will be incorrect.<br />
<br />
===Custom Class Options===<br />
If you are playing a class that is not part of the D&D 5E Compendium, you can input the important class information in this section, and checking the "Use Custom Class" checkbox will replace the main class selection with your custom built class.<br />
<br />
===Spell Slot Modifiers===<br />
This section allows you to manually modify how many spell slots your character has available for each spell level from 1 to 9.<br />
<br />
===Attribute Options===<br />
'''Attribute Modifiers:''' With this section you can manually adjust the individual Attribute Scores for Strength, Dexterity, Constitution, Intelligence, Wisdom, and Charisma.<br />
<br />
'''Initiative Modifier:''' Usually, your initiative modifier is just based off of your DEX modifier, but if you happen to find a magical item that enhances these rolls this is where you will put that bonus. This modifier will be used whenever the [[#.287.29_Armor_Class.2C_Initiative.2C_.26_Speed|Initiative]]-section is rolled on the Core page.<br />
<br />
'''Initiative Style:''' This setting allows you to select whether Initiative will be rolled with Advantage, Disadvantage, or rolled normally with a single d20 (default).<br />
<br />
'''Add DEX Tiebreaker to Initiative:''' If you would like to enable a tie breaker component to Initiative, this checkbox will enable adding your dexterity Attribute Score as a decimal value to your Initiative roll. So if you have a character with a dexterity attribute score of 14, your initiative modifier will change from a 2 to a 2.14.'<br />
<br />
'''Global Armor Class Modifier:''' This setting will modify your armor class and will be taken into account regardless of the equipment the character uses.<br />
<br />
'''Armor Class Tracking:''' There are three options available: The Automatic version that's default to the sheet where it adds 10 + your DEX modifer and then takes any armor equipped into account. A Custom version which expands out a formula upon selection where you can input your own formula for armor tracking, or you can turn Off Armor Tracking entirely. When turned off, you will need to manually adjust the Armor Class field on the Core page.<br />
<br />
===Save Options===<br />
'''Save Modifiers:''' With this section you can manually adjust the individual Save modifiers for Strength, Dexterity, Constitution, Intelligence, Wisdom, and Charisma.<br />
<br />
'''Death Save Modifier:''' A normal death save is usually just a D20 against a dc of 10, but if you're lucky enough to have a bonus to death saves, this is where you will put your bonuses. This modifier will be represented any time a "Death Save" is rolled from the Core page.<br />
<br />
'''Global Saving Throw Modifier:''' If you have an affect that would modify all saving throws, this option makes it easier to adjust your Save modifiers than having to go in and change each one individually. This modifier will be used every time any save is rolled from the sheet.<br />
<br />
===Skill Options===<br />
If your class offers the ability to achieve "Expertise" in a skill, or if you are using a Bard with the "Jack of All Trades" feat, this is where you will make these adjustments. There is also a section to add flat modifiers to any of your skills if your character has an archetype ability like Remarkable Athlete or a feat that adds a flat bonus to a skill. You can add expertise to any skill by clicking the value next to it and choosing "Expertise" from the drop-down menu. If your Bard has the Jack of All Trades feat, you can check the checkbox at the bottom of this section and it will automatically give half of your character's proficiency points to any skill check that doesn't have full proficiency.<br />
<br />
'''Passive Perception Modifier:''' This option will add a bonus to a character's Passive Perception which is not something you can change directly from the Core page of the sheet.<br />
<br />
===General Options===<br />
The General Options section has some important options that deal more with how the sheet works, rather than actual character creation. Most importantly, the NPC checkbox at the top, which will change the sheet to be the NPC version which is shaped to more easily track an NPC's information.<br />
<br />
'''Roll Queries - Always/Toggle/Query/Never Roll Advantage:''' This option will change how advantage is rolled for all attacks. It defaults to always roll advantage, which means that every time an attack is rolled it will roll twice and present the outcome of both rolls. This is useful for both advantage and disadvantage, otherwise you can just choose either the left or the right to be the default roll. Toggle adds a set of buttons at the top of the sheet to manually switch your advantage options between rolls. If Query is chosen, every time a roll is made it will ask you whether or not it's advantage. If Never is chosen, then it will always roll just a single dice per attack roll.<br />
<br />
'''Whisper Rolls to GM:''' Like above, you have the option to Never/Toggle/Query/Always whisper rolls to the GM. When this option is enabled, the attack roll will only be whispered to the GM and not made public.<br />
<br />
'''Auto Damage Roll:''' By default, damage rolls will not be rolled automatically, but only when you click the attack in the chat window. This is useful because you can choose to only roll damage when an attack hits. Using this option you can make the character always roll damage with every attack.<br />
<br />
'''Core Die Roll:''' You can change the core die (by default it is 1d20) to something else entirely here.<br />
<br />
'''Proficiency Bonus:''' By default, the character's Proficiency Bonus is calculated by class level. This setting allows you choose to calculate this bonus via By Level (the default), via a Proficiency Die as described in the Dungeon Master's Guide, or a Custom calculation which rolls out a field to enter a roll formula for the bonus.<br />
<br />
'''Global Save/Skill/Attack/Damage Modifier Field:''' This series of checkboxes will add new entries to the Saving Throws, Tools Proficiencies & Custom Skills, and Attacks & Spellcasting blocks respectively to add global modifiers (like if a character is under the effects of a Bless or Guidance spell). Each entry will have a Global label in grey at the bottom of its entry and a field to enter the modifier bonus. If you include a word in brackets with the bonus formula (ex. "1d4[Bless]"), the word enclosed in the brackets will appear when you mouse over a roll to see it's formula.<br />
<br />
'''Add Character Name to Templates:''' This option allows you to turn this on or off. When it is on, the character's name is listed in the roll template when rolls are made from the sheet. If the character sheet in question is for an NPC, you will likely want to have this off so the rolls don't accidentally show your hand of what sort of monster your party is facing. This setting is off by default.<br />
<br />
'''Auto Level Calculations:''' This option allows you to turn this on or off. When it is on, adjusting the character's class level will automatically update the character's proficiency bonus, Hit Dice, and spell Slot totals (if the class is a spellcaster).<br />
<br />
'''Encumbrance:''' This option dictates how encumbrance is handled on the Equipment block of the Core page. This requires your Inventory to be set to "Compendium Compatible" to automatically calculate and track the weight of your character's backpack if you enter the weight values for any of the items in your Equipment list. When your character becomes encumbered, and depending on its severity, the words ENCUMBERED, HEAVILY ENCUMBERED, or IMMOBILE will display in red underneath the TOTAL WEIGHT value. This setting has three options: Simple Encumbrance Rules, Variant Encumbrance Rules, or not follow Encumbrance rules at all by toggling it off from this.<br />
<br />
'''Inventory:''' With this option allows you to either have your Equipment block be "Compendium Compatible" or "Simple". The Simple version of the Equipment block will give you single text field to log your inventory. The Compendium Compatible version tracks weight, quantity, and attack options in an itemized list for every equipment item you add to the block.<br />
<br />
'''Features & Traits:''' This option can set the Features & Traits block to be either a single text field or a repeated section that will be Compendium Compatible to list traits and features in an itemized list.<br />
<br />
'''Proficiencies & Languages:''' This option can set the Proficiences & Languages block to be either a single text field or a repeated section that will be Compendium Compatible to list traits and features in an itemized list.<br />
<br />
'''Ammo Tracking (API Required):''' When using the 5th Edition OGL Companion API Script in your game (Pro Subscriber feature), you can set attacks to weapons using ammunition to automatically subtract from their tally in their Resource block. So if your character is equipped with a bow, rolling its attack will automatically remove an arrow from its Resource block.<br />
<br />
===Transition Options(outdated)===<br />
{{mbox | text = This feature doesn't seem to exist on the sheet any longer, so the info in this section is outdated}}<br />
<br />
If your campaign previously used the [https://wiki.roll20.net/DnD5e_Character_Sheet#Intro Community Contributed] or [https://wiki.roll20.net/index.php?title=DnD5e_Shaped_Character_Sheet&oldid=11112#General_Information Shaped Legacy] 5th Edition Character Sheets and you are swapping over to this one, we have an automated conversion tool that will clear or merge elements left over from those two sheets. This procedure can only be done ''once'' and can not be undone. It is recommended that you make a copy of your campaign first before attempting a sheet transition.<br />
<br />
There is also a checkbox that hides this feature entirely from the sheet. If you hide this by mistake, you can gain access to it again by creating a new character journal.<br />
<br />
=The NPC Sheet=<br />
''See Also:'' '''[[D&D5E by Roll20 NPC Attributes]]'''<br />
<br />
One of the most useful parts of the D&D 5E by Roll20 Character Sheet is that it contains both a PC sheet ''AND'' an NPC sheet. An NPC doesn't normally require the depth a PC sheet needs, so the NPC sheet is a much more slimmed down character sheet that doesn't require multiple pages like its PC counterpart. You can access this version of the sheet by going to the Settings Page, by clicking the gear icon near the top right of the sheet, and then checking the NPC checkbox. This will switch the sheet to the NPC version. You can switch back at any time by unchecking the NPC option under General Options on the new page.<br />
<br />
==NPC Options==<br />
[[File:5E_OGL_Sheet_NPC_Options.png|right|thumb|250px|The NPC Options Section]]This is the area where all of the NPC's stats will be entered, it covers everything from the NPC's name, to how strong or quick or smart it is, to what languages it speaks. Most of the fields in this section are just text fields used to keep track of information about the NPC. All of the information entered in these fields will be visible in the stat block once the NPC options are hidden. <br />
<br />
<br />
Any text that appears in light grey is placeholder text. It's there to offer you an example of what the content would be for any given field. <br />
<br />
By default, no skill or ability checks will show up in the NPC's stat block. Once you've added a value to the corresponding skill or ability save, they will appear. If for some reason the NPC will have to make a check with a skill or ability it does not have any bonus in, you can enter a 0 as the modifier for that check and it will add it to the list in the stat block below.<br />
<br />
The XP of an NPC auto-calculates based on its given challenge rating.<br />
<br />
If the NPC is a spellcaster, you can check the checkbox beside '''SPELLCASTING NPC''' and this will add a spell list section that utilizes the spell list and its functionality from the PC version of the sheet.<br />
<br />
At default, you can add Traits and Actions in their respective places after the Challenge Rating and XP area of the Stat Block. For Reactions and Legendary Actions, you need to enable them from the NPC Options section. For Reactions, check off the '''HAS REACTIONS''' checkbox. This will add a new sections to the Stat Block for you to add Reactions to. If an NPC is a monster with Legendary Actions then you must enter the number of actions that monster has access to each turn in the '''LEGENDARY ACTIONS:''' field. Once you add a number here, an additional section will appear in the stat block below, where you can add the specific legendary actions that the monster is able to do.<br />
<br />
The NPC sheet supports Compendium drag & drop. If you want to add a new monster to your game just drag the monster from the <span style="font-family:Pictos;">i</span> [[Compendium]]-tab of the [[Sidebar]] and drop it to anywhere on the Tabletop. This will automatically create a new journal entry named the same as the Compendium entry and will copy all of the information on that compendium page directly into the new sheet. If you have purchased any of the Compendium expansions that expands on the available NPCs like the Monster Manual or Volo's Guide to Monster, a token of that NPC will be added to the Tabletop that will have its stats automatically set and linked to the new journal entry.<br />
<br />
{{mbox | text = '''Note:''' If you already have a journal entry in your {{journal}}-tab with the exact same name as the <span style="font-family:Pictos;">i</span> [[Compendium]] entry, the drag and drop will not work as this automation will stop to prevent overwriting existing content the user has already created. If a drag and drop of an NPC Compendium page does not create a journal entry, run a search for that NPC's name in your Journal to see if an entry already exists. If you do not want to delete the older entry, renaming it will allow the drag and drop to work as expected.}}<br />
<br />
===General Options===<br />
Within the NPC Options section, directly below the Legendary Actions field, is the General Options that are featured on the PC Sheet: NPC checkbox, WHISPER ROLLS TO GM, and the AUTO DAMAGE ROLL options. <br />
<br />
*NPC checkbox<br />
*WHISPER ROLLS TO GM<br />
*AUTO DAMAGE ROLL<br />
*NPC NAME IN ROLLS<br />
*ADD DEX TO TIEBREAKER TO INITIATIVE<br />
<br />
Unchecking the NPC checkbox from here will revert the sheet back to the PC Sheet.<br />
<br />
===Hiding NPC Options===<br />
Once all of the desired information has been entered, you can click the <span style="font-family:Pictos;">y</span>(gear) icon at the top right to hide this section. This leaves behind just the NPC's stat block where you can make all of your rolls from. You can re-open this section to edit the information at any time by clicking on the <span style="font-family:Pictos;">y</span> icon again. It's in the same location regardless if you're looking at NPC Options or the NPC stat block.<br />
<br />
==The NPC Stat Block==<br />
[[File:5E OGL Sheet NPC v2.png|right|thumb|250px|An NPC stat block for a griffon]]Following NPC Options is the NPC Stat Block that is built off of what you input in the NPC Options section. This area may look very similar to a stat block you may find in a monster bestiary or published adventure.<br />
<br />
<br />
Any section of the stat block that has a corresponding roll will have click-able text. For example, if the NPC has to make a CON check, you can click the CON attribute to roll a CON check with all of the required modifiers automatically included. If you added a value to one of the skill modifier fields then that skill will show up in the NPC's "Saving Throws" list where you can click it to make a saving throw roll using that skill's modifier.<br />
<br />
The first section of the Stat Block mirrors all the information you added in the NPC Options section. This content is meant exclusively for rolling and can not be edited directly. You will need to change them from the NPC Options section.<br />
<br />
===Traits===<br />
Traits are pieces of information about an NPC that isn't covered by the NPC options section. These are entered directly onto the NPC's stat block. If you click the "<span style="font-family:Pictos;">&</span>" button that appears right below the "Senses/Languages/Challenge Rating" section it will add a blank entry where you can add a single trait for that NPC. Each Trait Entry features a bold title field which is then followed by a larger text box for the description of the trait. You can add any number of Traits for any NPC.<br />
<br />
===Actions===<br />
NPC actions can be used for any number of things. Each entry initially offers an Action Name field as well as a large text field for the Action description. The checkbox for ATTACK, once checked, adds more structured data fields needed for an attack roll (Type, Range/Reach, To Hit bonus, Target, Damage Roll, and Damage Type). To add a new entry you will select the <span style="font-family:Pictos;">&</span> button that appears below the Actions section. Once all of this is complete you can click the <span style="font-family:Pictos;">y</span>(gear) icon at the top of this entry to hide the input fields, leaving just the action text. You can show this information, or roll the attack, in the chat box by clicking the text for the action. If you need to make further modifications to any action you can hover over the row you wish to edit, then click on the <span style="font-family:Pictos;">y</span>(gear) icon again. This will show all of the action information input fields again. You can add any number of Actions for any NPC.<br />
<br />
===Bonus Actions===<br />
NPC bonus actions are typically not listed on the sheet, and are usually referenced in the Traits section. However, if a player wishes to use this section, it is available if the 'Bonus Action' checkbox is selected. The fields work the same as the Actions section.<br />
<br />
===Reactions===<br />
Once enabled from the NPC Options section, a new heading labeled "Reactions" and its relevant section is added to the stat block that allows you to add Reactions. These entries operate just like Traits.<br />
<br />
===Spells===<br />
Once enabled from the NPC Options section, a new heading labeled "Spells" and its relevant section is added to the stat block that allows you to add Spells. These entries will operate identically to how Spells are added and handled on the PC Sheet with the one noted exception that there is only a single column of spell entries. You can drag spells from the Compendium to add spell entries just like you would with the PC's Spell sheet. Any and all spells added to the character sheet are shared between the NPC and the PC versions.<br />
<br />
===Legendary Actions===<br />
If a number value is added to the LEGENDARY ACTIONS field in the NPC Options section, the Legendary Actions heading and section is added at the very bottom of the stat block and lists some verbiage on how many actions are available to be used on a given turn. This number is dictated by what you entered in the NPC Options. These entries operate the same way as Traits.<br />
<br />
==Rolling for Initiative for NPCs==<br />
There are two ways to roll for Initiative on the NPC sheet. You can click on the NPC's Name to roll for Initiative or you can roll from the die icon labeled INIT that is listed to the right of the Armor Class and Hit Points section of the NPC sheet, towards the top. If you have the Turn Tracker tool open, having the NPC token selected while rolling Initiative will automatically add the NPC and its initiative roll to the tracker. Creatures on the GM layer that are added to the tracker in this fashion will have their entries hidden from the players.<br />
<br />
<br />
You can also create a global Macro that will pop up as a Token Action button in the upper left hand corner of the tabletop every time a token is selected. This will allow you to roll without looking at the NPC sheet at all. The macro formula should look just like this:<br />
<br />
<code>%{selected|npc_init}</code><br />
<br />
=Advanced Use=<br />
<br />
===Custom Skills and Stats===<br />
You can set up any number of custom skills or rolls from the [[#Tool Proficiencies|Tool Proficiencies]] section just underneath the skill section on the Core tab. [[#Class & Other Resources|The Resources]] section is also useful for tracking custom stats to your campaign, game setting, or home-brew rules. There are also various options available from the Settings page to modify attributes, skills, saves, spells, and more.<br />
<br />
===Target Roll Buttons===<br />
A useful way for GMs and Players to reference their abilities is by dynamically setting up a handful of macros that can be used on a token linked to a character, rather than having to roll directly from the sheet. To do this, you'll set up a global macro from the {{Collections}}-tab. You can also write these directly in the {{Text Chat}}.<br />
<br />
In the examples, the <code>selected</code> part can be replaced with <code>target</code>, a character's name, or it's character ID.<br />
<br />
Here are some examples:<br />
<br />
'''PC'''<br />
* Attributes: <code>%{selected|strength}</code>, <code>%{selected|strength_save}</code> | Will roll the Strength Check and Strength Save for the selected [[token]](if the [[Link Token|token is linked to a sheet]])<br />
* <code>%{selected|acrobatics}</code><br />
* <code>%{selected|initiative}</code><br />
* <code>%{selected|death_save}</code><br />
* <code>%{selected|hit_dice}</code><br />
<br />
'''NPC'''<br />
* <code>%{selected|npc_init}</code><br />
* <code>%{selected|npc_str}</code><br />
* <code>%{selected|npc_stealth}</code><br />
* <code>%{selected|npc_hpformula}</code><br />
====Dynamic References to Repeating Sections====<br />
The example we'll be using today is setting up the 1st NPC action:<br />
<code>%{selected|repeating_npcaction_$0_npc_action}</code><br />
Now whenever you use this macro it will roll the first NPC action of whichever NPC token you have selected. You can set up a roll for each action by incrementing the 0 by 1 for each action you wish to add (I.E. <code>$1</code>, <code>$2</code>, <code>$3</code>). Here is a list of important repeating section rolls and their formulas:<br />
<br />
* Player Attack/Spell Attack <code>%{selected|repeating_attack_$0_attack}</code><br />
* Player Attack/Spell Damage <code>%{selected|repeating_attack_$0_attack_dmg}</code><br />
* Player Attack/Spell Critical Damage <code>%{selected|repeating_attack_$0_attack_crit}</code><br />
* Player Global DMG mod <code>%{selected|repeating_damagemod_$0_global_save}</code><br />
** Attr names: <code>global_damage_name</code>, <code>global_damage_damage</code>, <code>global_damage_critical_damage</code>, <code>global_damage_type</code><br />
* Proficiencies <code>%{selected|repeating_proficiencies_$0_output}</code><br />
* Tool/Custom Skill <code>%{selected|repeating_tool_$0_tool}</code><br />
* Traits/Feats: <code>%{selected|repeating_traits_$0_output}</code><br />
<br />
* Spellbook Cantrip <code>%{selected|repeating_spell-cantrip_$0_spell}</code><br />
* Spellbook Level 1 <code>%{selected|repeating_spell-1_$0_spell}</code><br />
* Spellbook Level 2 <code>%{selected|repeating_spell-2_$0_spell}</code><br />
* Spellbook Level 3 <code>%{selected|repeating_spell-3_$0_spell}</code><br />
* Spellbook Level 4 <code>%{selected|repeating_spell-4_$0_spell}</code><br />
* Spellbook Level 5 <code>%{selected|repeating_spell-5_$0_spell}</code><br />
* Spellbook Level 6 <code>%{selected|repeating_spell-6_$0_spell}</code><br />
* Spellbook Level 7 <code>%{selected|repeating_spell-7_$0_spell}</code><br />
* Spellbook Level 8 <code>%{selected|repeating_spell-8_$0_spell}</code><br />
* Spellbook Level 9 <code>%{selected|repeating_spell-9_$0_spell}</code><br />
<br />
'''NPC'''<br />
* NPC Traits/Abilities<code>%{selected|repeating_npctraits_$0_npc_roll_output}</code><br />
* NPC Actions/Attacks<code>%{selected|repeating_npcaction_$0_npc_action}</code><br />
* NPC Attack Damage<code>%{selected|repeating_npcaction_$0_npc_dmg}</code><br />
* NPC Attack Critical Damage<code>%{selected|repeating_npcaction_$0_npc_crit}</code><br />
* NPC Bonus Actions<code>%{selected|repeating_npcbonusaction_$0_npc_action}</code><br />
* NPC Legendary Actions<code>%{selected|repeating_npcaction-l_$0_npc_action}</code><br />
* NPC Mythic Actions<code>%{selected|repeating_npcaction-m_$0_npc_action}</code><br />
* NPC Spells<code>%{selected|repeating_spell-npc_$0_spell}</code><br />
<br />
===Directly Referencing Attributes===<br />
You can discover the name of most of the attributes in the sheet by hovering over them. After a couple of seconds a title will pop up and tell you how to referencing them. You can call attributes in an Ability Rolls by using <code>@{attributename}</code>. If you want to directly reference it in a roll that isn't saved on the sheet, you need to specify the character's name, or use either the <code>selected</code> or <code>target</code> key works.<br />
<br />
'''Examples:'''<br />
* <code>/em attempts to grapple and gets [[1d20+@{strength_mod}]]</code> custom [[Journal#Attributes_.26_Abilities_Tab|Ability call]], saved in the "attributes and abilities" tab of the character sheet.<br />
* <code>/r 1d20+@{Alice|strength_mod}+@{Alice|pb}</code> macro that calls a specific character<br />
* <code>/em have @{selected|hp} out of @{selected|hp|max} left.</code> macro that uses stats from a token(token must be selected before rolling)<br />
* <code>The Enemy's AC is @{target|npc_ac}</code> macro prompt the user to select a target token on the map, and uses it's stats.<br />
<br><br />
<br />
See [[Macros#Attribute_Macros]] for further general details/examples on the syntax.<br />
====PC====<br />
Here are a list of some of the more important stats:<br /><br />
<br />
'''Attributes/Saves:'''<br />
<br />
* Str: <code>strength, strength_mod, strength_save_bonus</code><br /><br />
* Dex: <code>dexterity, dexterity_mod, dexterity_save_bonus</code><br /><br />
* Con: <code>constitution, constitution_mod, constitution_save_bonus</code><br /><br />
* Int: <code>intelligence, intelligence_mod, intelligence_save_bonus</code><br /><br />
* Wis: <code>wisdom, wisdom_mod, wisdom_save_bonus</code><br /><br />
* Cha: <code>charisma, charisma_mod, charisma_save_bonus</code><br />
<br><br />
'''Skills:'''<br />
<br />
<code>athletics_bonus<br /><br />
acrobatics_bonus<br /><br />
animal_handling_bonus<br /><br />
arcana_bonus<br /><br />
deception_bonus<br /><br />
history_bonus<br /><br />
insight_bonus<br /><br />
intimidation_bonus<br /><br />
investigation_bonus<br /><br />
medicine_bonus<br /><br />
nature_bonus<br /><br />
perception_bonus, passive_wisdom<br /><br />
performance_bonus<br /><br />
persuasion_bonus<br /><br />
religion_bonus<br /><br />
sleight_of_hand_bonus<br /><br />
stealth_bonus<br /><br />
survival_bonus<br /><br />
</code><br />
<br />
'''AC, Proficiency, HD etc'''<br />
<br />
<code>pb</code>(Proficiency Bonus)<br><br />
<code>inspiration</code><br><br />
<code>ac<br /><br />
initiative_bonus<br /><br />
speed<br /><br />
hp, hp|max, hp_temp<br /><br />
hit_dice, hit_dice|max, hitdietype<br /><br />
weighttotal<br /><br />
</code><br />
<br />
'''Spells'''<br />
<br />
<code>spell_save_dc, spell_attack_bonus<br /><br />
lvl1_slots_total, lvl1_slots_expended<br /><br />
lvl2_slots_total, lvl2_slots_expended<br /><br />
lvl3_slots_total, lvl3_slots_expended<br /><br />
lvl4_slots_total, lvl4_slots_expended<br /><br />
lvl5_slots_total, lvl5_slots_expended<br /><br />
lvl6_slots_total, lvl6_slots_expended<br /><br />
lvl7_slots_total, lvl7_slots_expended<br /><br />
lvl8_slots_total, lvl8_slots_expended<br /><br />
lvl9_slots_total, lvl9_slots_expended<br /><br />
</code><br />
<br />
Spells, repeating sections:<br><br />
<code>repeating_spell-cantrip<br><br />
repeating_spell-1<br><br />
repeating_spell-2<br><br />
repeating_spell-3<br><br />
repeating_spell-4<br><br />
repeating_spell-5<br><br />
repeating_spell-6<br><br />
repeating_spell-7<br><br />
repeating_spell-8<br><br />
repeating_spell-9</code><br> <br />
<br />
Cantrip stats(most should also work for lvl.1-lvl.9):<br><br><br />
Full statname is spell level + (rowID or row number) + attribute name, e.g. <code>repeating_spell-1_$0_spellname</code> is the spell name of your first Lvl 1 spell, <code>repeating_spell-4_$1_spelldescription</code> is the description of your second lvl.4 spell.<br />
<br />
<code>spellname<br><br />
spellrange, spellcastingtime, spelltarget, spellduration<br><br />
spellschool<br><br />
spellritual<br><br />
spellconcentration<br><br />
spellcomp_v, spellcomp_s, spellcomp_m<br><br />
spellcomp_materials<br><br />
spell_ability<br><br />
spelloutput<br><br />
spellattack<br><br />
spelldamage, spelldamagetype, spelldamage2, spelldamagetype2<br><br />
spellhealing<br><br />
spelldmgmod, spell_damage_progression<br><br />
spellsave, spellsavesuccess<br><br />
spelldescription<br><br />
spellclass, spellsource</code><br />
<br />
'''Items'''<br><br />
<code>cp sp ep gp pp</code><br><br />
(copper pieces, silver, gold, electrum, platinum)<br />
<br />
<code>repeating_inventory_$#_itemcount<br><br />
repeating_inventory_$#_itemname<br><br />
repeating_inventory_$#_itemweight<br><br />
repeating_inventory_$#_equipped<br><br />
repeating_inventory_$#_useasresource<br><br />
repeating_inventory_$#_hasattack<br><br />
repeating_inventory_$#_itemproperties<br><br />
repeating_inventory_$#_itemmodifiers<br><br />
repeating_inventory_$#_itemcontent</code><br><br />
<br />
* <code>equipped</code>, <code>useasresource</code>, <code>hasattack</code> are checkboxes, with value 1 if checked.<br />
* <code>itemmodifiers</code> is for of item changes any stats, like <code>AC +2</code> adding +2 to AC when equpped.<br />
* <code>itemcontent</code> is the item description<br />
<br><br />
'''The class_resource and the other_resource'''<br><br />
<br />
<code>class_resource</code> and <code>other_resource</code> are static resources. That is to say, you need to keep in mind that they are NOT a part of the repeating section, even though it definitely looks that way on the character sheet.<br><br />
<br />
You use these to access them<br />
<br />
<code>class_resource</code><br><br />
<code>class_resource_max</code><br><br />
<code>class_resource_name</code><br><br />
<code>other_resource</code><br><br />
<code>other_resource_max</code><br><br />
<code>other_resource_name</code><br><br />
<br />
'''The repeating resources'''<br><br />
<br />
Any resources that appear beneath the "class resource" and the "other resource" are a part of the "repeating resources" section. This section is known for being confusing for beginners, so it deserves a bit of clarification.<br />
<br />
First, keep in mind that this is one section (not two sections, as people often think), and that "repeating_resource" is its section prefix.<br />
<br />
Second, keep in mind that you need to skip past the row with the "class resource" when you're figuring out the address of the row that you want to refer to. So basically, if you want to refer to the row that is directly below the row with the "class_resource", then you would add "_$0" (to form "repeating_resource_$0"). And then the next row after that is "_$1", and so on.<br />
<br />
Third, keep in mind that if you add "_resource_left" (to form "repeating_resource_$0_resource_left"), then you are specifying that you are talking about the CURRENT VALUE of the leftmost resource in that row. And if you add "_resource_left_max", then you are specifying that you are talking about the MAX VALUE of the leftmost resource in that row.<br />
<br />
Here is a complete list of all the fields that you can access in the "repeating_resource" section. Just replace the "#" character with which row you want to access.<br />
<br />
<code>repeating_resource_$#_resource_left</code><br><br />
<code>repeating_resource_$#_resource_left_max</code><br><br />
<code>repeating_resource_$#_resource_left_name</code><br><br />
<code>repeating_resource_$#_resource_right</code><br><br />
<code>repeating_resource_$#_resource_right_max</code><br><br />
<code>repeating_resource_$#_resource_right_name</code><br><br><br />
<br />
<br />
'''Features/Class Traits'''<br />
<br />
<code>repeating_traits_$0_output<br><br />
repeating_traits_$#_name<br><br />
repeating_traits_$#_source<br><br />
repeating_traits_$#_source_type<br><br />
repeating_traits_$#_description<br><br />
</code><br />
<br />
'''Other/Settings:'''<br />
<br />
<br><br />
<code><nowiki>wtype</nowiki></code> (whisper type, can have one of these values:)<br />
* <code><nowiki></nowiki></code> (empty for never whisper)<br />
* <code><nowiki>@{whispertoggle}</nowiki></code> (show the buttons on sheet that can toggle between options)<br />
* <code><nowiki>?{Whisper?|Public Roll,|Whisper Roll,/w gm }</nowiki></code><br />
* <code><nowiki>/w gm</nowiki></code> (always whisper)<br />
<br />
<br />
'''Global modifiers'''<br />
<br />
* <code>repeating_savemod_$0_global_save_roll</code><br />
* <code>repeating_skillmod_$0_global_skill_roll</code><br />
* <code>repeating_tohitmod_$0_global_attack_roll</code><br />
* <code>repeating_damagemod_$0_global_damage_damage</code><br />
<br />
====NPC====<br />
Some stats are the same as for PCs<br />
<br />
<code>npc_name<br><br />
npc_ac<br><br />
hp, hp|max<br><br />
npc_speed<br><br />
npc_challenge<br><br />
npc_xp</code><br />
<br />
Attributes: <code>strength_base, strength_mod</code> (same as PCs)<br />
Saves:<br />
<br />
<code>npc_str_save_base</code>,<code>npc_dex_save_base</code>, <code>npc_con_save_base</code>,<code>npc_int_save_base</code>,<code>npc_wis_save_base</code><code>npc_cha_save_base</code><br />
Skill bonus:<code>npc_acrobatics_base</code>, <code>npc_animal_handling_base</code> etc.<br />
<br />
Damage/Conditions stuff:<br />
<br />
<code>npc_vulnerabilities<br><br />
npc_resistances<br><br />
npc_immunities<br><br />
npc_condition_immunities</code><br />
<br />
Spells:<br />
<br />
<code>npcspellcastingflag</code> (set to "1" if caster, empty otherwise) <br />
<code>spellcasting_ability</code><br />
<code>globalmagicmod </code> (global magic attack modifier)<br />
<code>caster_level</code><br />
<code>spell_dc_mod</code> (spell save DC mod)<br />
<br />
Spells are identical to PC section<br />
<br />
Other:<br />
whisper is same as PCs<br />
<br />
<code>npc_name_flag</code> (show/hide npc name in rolls, value is either <code><nowiki>{{name=@{npc_name}}}</nowiki></code> or <code>0</code>)<br />
<br />
<br />
<sup>Note: anything with the Suffix of <code>|max</code> requires some form of Prefix, such as <code>selected|</code> making the call for such a thing look something along the lines of <code>@{selected|hp|max}</code>. The <code>|max</code> Suffix specifically calls the box on the right of the selected Attribute's Line, for example, you could fill in the Weight Total's 2nd Box with <code>@{strength}*15</code> & whenever you call <code>@{selected|weighttotal|max}</code> it will tell you your 5e standard Maximum Carry Capacity for your current Strength Score.<br />
<br />
===Custom AC Items===<br />
You can add pieces to your inventory and manually give them AC or magic bonuses that will figure into their calculations automatically. Inside the item options is a section for "MODS:". Add <code>Ac +1</code> to add an armor class bonus.<br />
<br />
===Roll Templates===<br />
''Main Article:'' '''[[D&D 5e by Roll20 Roll Templates]]'''<br />
<br />
The '''D&D5E by Roll20''' Character Sheet also includes a series of [[Roll Templates]] that you can use to dress up your own custom macros. Roll Templates provide additional layout and styling options for the display of roll results.<br />
<br />
{{ex}}<br />
[[File:5e-rolltemplate-ex1-2021.png|200px|right|none]]<br />
Rolls stealth for selected npc token, using it's stealth proficiency.<br />
<code><nowiki>/w gm &{template:npcatk} {{attack=1}} {{name=Shadow}} {{rname=Shadow Stealth}} {{rnamec=Hide}} {{r1=[[@{selected|d20}+@{selected|npc_stealth} + 6]]}} {{always=1}} {{r2=[[@{selected|d20}+@{selected|npc_stealth} + 6]]}} {{description=While in dim light or darkness, the shadow can take the Hide action as a bonus action. Its stealth bonus is **also** improved to +6 }}</nowiki></code><br />
<br />
===Magic Missile Spell===<br />
{| role="presentation" class="wikitable mw-collapsible mw-collapsed" style="float:right; margin-left: 10px;margin-right: 60px;"<br />
| Image of the Spell's settings<br />
|-<br />
| [[File:Magic-Missile-5E-2020.png|right|frame|The Magic Missile Spell]]<br />
|}<br />
<br />
RAW, Magic Missile is rolled once, and the single roll is then used for each hit. So by default the spell rolls <code>1d4+1</code>. (See [[Talk:D&D 5E by Roll20#Old Magic Missile Discussion]] for more info.)<br />
<br />
You can modify the spell to instead roll 3d4+3 at first level, and then in the ''HIGHER LVL CAST DAMAGE'' section, set it to <code>1d4+1</code>.<br />
<br />
To automatically use higher-level spell slots with Magic Missile, you have to write a 0 into the ''HIGHER LVL CAST DAMAGE'' section of the spell and select any die. It will show the box for selecting higher-level spell slots when launching Magic Missile, but since it multiplies the higher-level damage cast by 0, the added roll doesn't show up in the chat, making it roll a single die for every missile while using any level spell slot.<br />
<br />
=API=<br />
{{pro only|section}}<br />
[[API:Introduction|API Scripts]] allow for greater customization and functionality to how Roll20 operates beyond what it can do at default. This section will list some info on using various APIs that interact with the character sheet.<br />
<br />
Example of APIs from the One-Click Install menu, that designed to be used with the '''D&D 5E by Roll20''' sheet:<br />
* '''5E BattleMaster'''<br />
* '''5E Resting in Style'''<br />
* '''CashMaster'''<br />
* '''Concentration'''<br />
* '''[[Script:It's a Trap|It's a Trap! -- D&D 5E Generic]] (should detect automatically what sheet is used)<br />
** {{repo|Roll20/roll20-api-scripts/tree/master/ItsATrap_theme_5E_Generic#readme readme}}<br />
* '''ShortRest'''<br />
* '''SpellMaster'''<br />
* '''WildShape'''<br />
<br />
A good number of the more general APIs have built in settings for configuring them for usage with the 5E sheet, such as '''GroupInitiative''', '''GroupCheck''', '''Experience Tracker''', '''[[PowerCards]]''', '''[[ScriptCards]]''' (ScriptCards is an improved version of PowerCards)<br />
<br />
* '''[[GroupCheck]]:''' <code>!group-check-config --import 5E-OGL</code> will configure the API for use with this sheet<br />
* '''[[GroupInit|GroupInitiative]]:''' before use, API need to be configured for the sheet, either through the menu preset, or using the command: <code>!group-init --add-group --Bare </code><br />
* '''CombatMaster:''' is by default configured with conditions for D&D 5E<br />
* '''[[ChatSetAttr]]:''' API that can create, edit, & delete stats on sheets. Example: [[Script:ChatSetAttr#Add_new_thing_to_Repeating_Section|Adding a new magic item to a sheet]], with one chat command <br />
* '''[[Script:Ammo]]''' can be used for updating ammo & spellslots when used<br />
<br />
==Utilizing the ''5th Edition OGL by Roll20 Companion'' API Script==<br />
'''{{repo|Roll20/roll20-api-scripts/tree/master/5th%20Edition%20OGL%20by%20Roll20%20Companion 5th Edition OGL Companion}}'''is an official companion script for the "D&D 5E by Roll20" character sheet. The Companion currently supports Ammo Tracking, Automatic NPC Tokens, Automatic Death Save Tracking, and Automatic Spell Slot Tracking. <br />
<br />
{{mbox | text = Installing & creating [[API]] Scripts is a {{Pro}} feature. In order to be able to access these advanced scripts, the [[GM]] of the campaign must be a [[Pro]] subscriber and enable it for their campaign.}}<br />
<br />
<br />
'''''How to Add the API Script to your Game'''''<br />
<br />
If you have a PRO account, you can install the API script by going to your game's Campaign Page and clicking on the '''Settings''' button, and then choosing '''API Scripts'''. This brings you to the API Scripts page for your current game. The Companion Script is part of the One-Click Community API Installation options. Under the Script Library tab, there is a drop down menu that lists all the available community created scripts. Scroll down till you find the '''System Toolbox''' category and select the "5th Edition OGL by Roll20 Companion" script. The version number, the script's author, and a brief description of what the script does will appear right below the drop down menu once it is selected. Below that, click on the blue "Add Script" button to add the script to your game.<br />
<br />
<br />
'''''List of API commands for the 5th Edition OGL Companion API Script'''''<br />
* <code>!5ehelp</code> - Gives a list of the script's API commands in the chat tab.<br />
* <code>!5estatus</code> - Lists the current status of the script's features in the chat tab.<br />
* <code>!ammotracking on/off/quiet</code> - Automatically expends linked resource when attack is made<br />
* <code>!autonpctoken on/off</code> - Automatically generates a NPC token on the GM's screen based on the default token when an NPC's health calculation is rolled<br />
* <code>!deathsavetracking on/off/quiet</code> - Automatically ticks off successes and failures when death saves are rolled, clearing on death, stabilization, or hp recovery<br />
* <code>!longrest <character name></code> - This will add Hit Dice recover and if spelltracking is on, this command will reset all of the character's spell slots to unspent.<br />
* <code>!npchp <character name></code> - Rolls NPC hit point totals using their formula and updates the token bar. If no character name is provided it will roll the selected tokens.<br />
* <code>!spelltracking on/off/quiet</code> - Automatically expends spell charges as cast, factoring in higher level casting, and spells marked as Rituals will not spend a spell slot.<br />
<br />
<br />
Options:<br />
* ''on'' - Toggles the functionality on (default)<br />
* ''off'' - Disables the functionality<br />
* ''quiet'' - Maintains functionality while preventing results from being output to the chat.<br />
<br />
<br />
===Automatic Ammunition Tracking===<br />
''Main Article:'' '''[[D&D 5E by Roll20: How to setup Ammunition and Resource tracker]]'''<br />
<br />
Automatic Ammunition Track is a feature that requires the above Companion API Script. Once installed, follow these instructions to enable automatic ammunition tracking in your game:<br />
<br />
This example sets up a Longbow with a quiver of Arrows to track.<br />
# On the Settings (Gear Icon) tab of a character sheet, under GENERAL OPTIONS, make sure that the INVENTORY option is set to "Compendium Compatible" and not "Simple".<br />
# While still under GENERAL OPTIONS, set the AMMO TRACKING feature to ON.<br />
# Create manually or drag a missile weapon (ex. Longbow) from the Compendium to your sheet.<br />
# Create manually or drag a missile type (Arrows) from the compendium to your sheet<br />
# Expand the missile type (Arrows) by clicking on the "I" information icon that appears when hovering the mouse over the item.<br />
# Select the USE AS RESOURCE checkbox. (ammunition items dragged from the Compendium will have this option automatically checked off)<br />
# On the CORE tab, expand the missile weapon (Long Bow) in the ATTACKS & SPELLCASTING section by clicking on the gear icon that appears when hovering over the attack.<br />
# In the AMMUNITION section put the exact name of the ammunition resource (Arrows). If you want to spend more than one piece of ammunition per shot you want to add the number of pieces after the name of the ammunition resource and a comma. (ex. ''Arrows,2'' )<br />
<br />
<br />
Now, any time the missile weapon (Longbow) is rolled, a piece of ammunition will automatically be spent and the chat will make note. Additionally after the first time the missile weapon is used the AMMUNITION section will update with the ID of the resource repeating section, this is normal and expected.<br />
<br />
<br />
===Automatic Spell Slot Tracking===<br />
<br />
Automatic Spell Slot Tracking is a feature that requires the above Companion API Script. Once installed, follow these instructions to enable automatic spell slot tracking in your game:<br />
* In the chat input area of the Sidebar, type ''!5estatus'' and press Enter, to check if spelltracking is set to 'on'.<br />
* If not, type ''!spelltracking on'' and press Enter to activate this feature.<br />
* Alternatively, you may type ''!spelltracking quiet'' and press Enter to activate this feature, while preventing spelltracking messages from being displayed in the chat.<br />
<br />
<br />
<br />
Once the Spell Slot Tracking has been activated, each time a spell is cast:<br />
# The number of cast spells of the appropriate level is updated in the Spell tab of the character sheet (see [[5th Edition OGL by Roll20|Spell Levels & Spells Per Day]]).<br />
# A message is output in the chat, displaying the spell level, the number of available spell slots and the number of used spell slots for this level.<br />
# Spell slots decrement as spells are cast. <br />
# Spells that are marked as a Ritual do not affect the tally of spell slots when cast.<br />
<br />
<br />
At any time, you can manually adjust this count directly in the Spell Page of the character sheet.<br />
<br />
=Updates=<br />
* {{hc|articles/360037772613-Change-Log Roll20 Changelog}} - Full Changelog of Roll20, updates for 5E sheet are included<br />
* {{fpl|10096810/ D&D 5th Edition by Roll20 (Q2Y2021)}} often has mentions of latest updates<br />
* Major Sheet Updates:<br />
** Feats can now be selected in Charactermancer {{fpl|8891809 June 2020}}<br />
** Game [[creator]] can select which [[compendiums]] are or aren't accessible in a game. [https://app.roll20.net/forum/post/8738570/release-note-for-may-26-2020 May 26 2020]<br />
<br />
=Known Issues=<br />
The sheet has a number of known bugs and issues, some which are mentioned in the sheet's latest forum thread.<br />
<br />
'''Charactermancer/Character Creation'''<br />
* '''Charactermancer & Compendium drag-n-drop doesn't work when sheet is in a separate window.''' This is [[Character_Sheets#Character_Sheet_in_a_separate_window|an inherit limitation to how character sheets work]] at the moment. <br />
* '''Multiclassing & spell selection''' - There are troubles when multiclassing spellcasters and getting to select spells from the right lists.<br />
* '''Duplicate races/classes from Essential Kit appear in selection''' You need to uncheck EK from your compendium for it to no longer appear in selections.<br />
<br />
<br />
'''General:'''<br />
* '''Warlock spell slots''' - The Warlock's spell slots don't work too well with the sheet, and most people use some manual adjustments for how they work. The number of spell slots also appears wrong in the Charactermancer.<br />
* '''NPC stat <code>desc</code> changed into <code>description</code>''' This was a recent update that broke some macros for people, resulting in error messages along: "can't find ''desc'' attribute" {{fpl|8297517/ release notes march 2020}}<br />
<br />
=Sheet Guides=<br />
* [[5E Macros]]<br />
* {{blog|638339117446578176/tome-of-tips-dungeons-dragons-5th-edition-ogl Tome Of Tips: The D&D 5E character sheet}}<br />
* {{yt.be|9BGGr97qJdY|Learning Roll20: EP01 Character Sheets (D&D 5E)}} 50min, by Roll20 (2020)<br />
<br />
=Related Pages=<br />
* D&D 5E by Roll20 sheet<br />
** [[D&D5E by Roll20 NPC Attributes]]<br />
** [[D&D 5e by Roll20 Roll Templates]]<br />
** [[D&D 5E by Roll20: How to setup Ammunition and Resource tracker]]<br />
* [[5E]] - general D&D 5E info for Roll20. Lists also the alterantive character sheets for 5E<br />
* [[D&D]] - Roll20 stuff on the various editions.<br />
* {{Compendium}}<br />
** [[Compendium Sharing]]<br />
* [[Character Vault]]<br />
<br />
=See Also=<br />
* {{repo|Roll20/roll20-character-sheets/tree/master/DD5thEditionLegacy Sheet sourcecode}} - (Public version of sheet code is 1½+ years behind from what is actually used)<br />
* {{hc|articles/360037772613-Change-Log Roll20 Changelog}} - Full Changelog of Roll20, updates for 5E sheet are included<br />
<br /><br />
<br /><br />
[[Category:Character Sheet Documentation]]<br />
[[Category:Official Sheet]]<br />
[[Category:DnD5E]]<br />
[[Category:Featured articles]]</div>5004103https://wiki.roll20.net/D%26D_5E_by_Roll20D&D 5E by Roll202021-10-11T12:44:48Z<p>5004103: /* API */</p>
<hr />
<div>{{revdate}}{{HCbox|{{hc|360037773573-5th-Edition-OGL-by-Roll20 D&D 5E by Roll20}} }}<br />
[[File:5E OGL Sheet Core v2.6.png|500px|thumb|right|The '''D&D 5E by Roll20''' Character Sheet]]<br />
<br />
This is the community-driven documentation for the '''[[5E|D&D 5E]] by Roll20''' character sheet. Previously the sheet was known as the '''"5th Edition OGL Sheet"''' or just the '''"OGL Sheet"'''.<br />
<br />
=The Basics=<br />
This page is a ''[[Community Wiki]]'' guide to the Official D&D 5th Edition character sheet, which is updated with info tricks that might not be covered by the {{hc|articles/360037773573-5th-Edition-OGL-by-Roll20 official sheet documentation}}.<br />
<br />
<br />
To find out about the latest updates, issues and talk about the sheet, check the {{fpl|10096810/ D&D 5th Edition by Roll20 (Q2Y2021)}}-thread on the {{forum|category/277980 forums}}.<br />
<br />
<br />
[[Bug|Bug reports]] for the sheet is best reported in the same thread. If you find bugs in the 5E Compendium or 5E marketplace content, {{bug}}.<br />
<br />
<br />
__TOC__<br />
<br />
==Adding the Character Sheet to a Game==<br />
[[File:D&D5E-Roll20-sheet-selection.png|300px|thumb|right|The Sheet Selection Menu]]An official or community contributed character sheet [[Add_character_sheet#Adding_a_Character_Sheet_to_your_Campaign|can be added to any game when you first create it]]. On the Game Creation screen, underneath the large blue '''“I’m Ready, Create Game!”''' button, is the '''“Optional: Choose a Character Sheet”''' section. Located here is a drop down menu that lists all the character sheets built either by Roll20 officially or created by the community. These sheets are sorted under their respective RPG Systems in alphanumerical order. Once selected, a preview of the character sheet will load upon the creation page for you to review as well as showcase relevant information about the sheet, such as the sheet’s creator and its key features.<br />
<br />
<br />
The '''D&D 5E by Roll20''' Sheet can be found under either: '''Sheets by Roll20''' → D&D 5E by Roll20 OR '''Dungeons and Dragons 5E''' → D&D 5E by Roll20<br />
<br />
<br />
If you want to add a character sheet to an existing campaign, you can find this drop down menu once again by accessing the [[Game Settings Page]] from the [[Game_Management#Game_Details_Page|Game Details]]-page.<br />
<br />
{{mbox | text = '''NOTE:''' If you have added custom attributes to your character journals prior to adding a character sheet to a campaign, you may want to delete them first. Adding a character sheet to a campaign will create its own set of custom attributes on all of your character journals, but it will reuse any attributes encountered if they share the same name. This can cause calculation issues on the sheet.}}<br />
<br />
<br />
If you were previously using either the [[DnD5e Shaped Character Sheet|D&D 5E (Shaped)]] or [[DnD5E_Community_Contributed|D&D 5E (Community Contributed)]] sheets and wish to transfer over to the '''D&D 5E by Roll20''' version, it's a good idea to ask help on the [https://app.roll20.net/forum/category/277980 forums].<br />
<br />
<div style="clear: both"></div><br />
<br />
==Where to Find the Sheet==<br />
Once a character sheet has been added to a game, and once inside it, on all [[Journal#Characters|Characters Journals]], a new tab will be available between the '''“Bio & Info”''' and '''“Attributes & Abilities”''' tab labelled '''“Character Sheet”'''. Much like the Attributes & Abilities tab, only players who have been granted Edit permissions for the journal entry will be able to access the Character Sheet tab.<br />
<br />
''See also:'' '''[[Add_character_sheet#Adding_New_Characters_In-Game|Create new character sheets to your players]]'''<br />
<br />
==Sheet Features==<br />
The '''D&D 5E by Roll20''' sheet has all of the functionality of a pen and paper character sheet, and much more. Certain aspects of the sheet have been streamlined or automated to remove bookkeeping and speed up gameplay. The key features are auto-calculations, [[Macro|macro]] buttons, and [[D&D 5e by Roll20 Roll Templates|roll templates]]. The sheet defaults to using the rules as printed in the D&D 5E SRD, however it's dynamic enough to allow you and your group to use many custom house rules you might want.<br />
<br />
===Auto Calculations===<br />
Many parts of the sheet use auto calculations to fill in derived attributes with the expectation that you're using the rules as printed in the 5th Edition SRD. Many of these calculated traits can be modified from the character sheet's <span style="font-family:Pictos;">y</span> [[D&D 5E by Roll20#Settings Page|Settings]]-tab, and those set by Sheet Workers can be edited directly. Below are some examples of Sheet Worker and Auto Calculation functionality:<br />
<br />
* '''Class''' - Changing the character's class from the header will automatically update the character's saving throw proficiencies, their hit die type, spell casting ability, and spell save DC. <br />
* '''Level''' - Changing the character's level will also update their proficiency bonus, number of spells per day, and more.<br />
* '''Attributes''' - Changing one of the character's attributes will also update the related modifier, skills that are based on that attribute, and derived stats such as initiative or passive perception.<br />
<br />
===Roll Buttons and Roll Templates===<br />
[[File:5E_OGL_Sheet_Rollable_Buttons.gif|right|frame|Any label that highlights in red when the mouse hovers over it is rollable.]]<br />
''Main Page:'' '''[[D&D 5e by Roll20 Roll Templates|D&D 5E by Roll20 Roll templates]]'''<br />
<br />
Most of the stats in the game can be rolled by hovering over their name, the stat will turn red, and then left-clicking the mouse. This is true for Attributes, Saves, Skills, Hit Dice, Death Saves, Tool Proficiencies, Attacks & Spellcasting, Spell Cards, and NPC Actions/Attacks. Any of these roll buttons can be dragged directly from the sheet to your [[Macro Quick Bar]], enabled from the <span style="font-family:Pictos;">y</span> [[My Settings]]-tab of Roll20's [[Sidebar]].<br />
<br />
Player characters have both a simple and attack [[D&D 5e by Roll20 Roll Templates|roll template]] that is output to the {{Text Chat}}-tab on the right hand [[Sidebar]]. The simple template is used for everything except for attacks. The attack template is shaped to show up in three pieces; the attack at the top, information in the middle, and damage at the bottom. Depending on your sheet settings, the damage will not roll automatically unless you click on the name of the attack from the roll template in the chat tab. This was designed to simulate the tabletop experience of rolling to attack and then rolling damage if necessary. You can change this behavior in the sheet <span style="font-family:Pictos;">y</span> [[D&D 5E by Roll20#Settings Page|Settings]]-tab, tab under "Auto Damage Roll".<br />
<br />
<div style="clear: both"></div><br />
<br />
====Rolling for Advantage and Disadvantage====<br />
With the '''D&D 5E by Roll20''' Sheet, the [[D&D 5E by Roll20#Settings Page|default sheet settings]] has Advantage set to ''always'' rolled for convenience purposes. It is commonly agreed upon that a gaming group uses the left roll result when advantage is not being used for a check. When advantage or disadvantage is in play, simply choose the higher or lower result among the two per usual. You can change this behavior in the sheet <span style="font-family:Pictos;">y</span> [[D&D 5E by Roll20#Settings Page|Settings]]-tab (gear icon at the top right of the page), tab under "Roll Queries". You have the choice of "Always Roll Advantage" (the default setting), "Advantage Toggle", "Query Advantage", or "Never Roll Advantage".<br />
<br />
'''Advantage Toggle:''' The Advantage Toggle will add three buttons to the top of your character sheet: "Advantage", "Normal", and "Disadvantage". You can click on any of these to roll for Advantage (the highest roll result will highlight in black), Disadvantage (the lowest roll result will highlight in black), or a single d20.<br />
<br />
'''Query Advantage:''' The Query Advantage setting will prompt a dialog box to appear whenever you roll from your sheet. It will ask you to select what sort of roll want to do (Normal, Advantage, Disadvantage). After choosing the type you want, the roll will occur in chat.<br />
<br />
'''Never Roll Advantage:''' When rolling from your sheet, only a single d20 will be rolled.<br />
<br />
===Resizable Text Fields===<br />
[[File:5E_OGL_Sheet_Resizable_Text_Fields.gif|right|frame|Making a text field larger is just a matter of click and dragging.]]There are many free-text fields on the sheet that give you a place to keep information that doesn't necessarily follow a specific format. All of the fields on the Bio Tab are free-text fields as well as the Description fields present for attacks, spells, equipment, features & traits, and NPC actions. If your text overflows past the bottom of a text field, you can resize it to view the content in its entirety by clicking and dragging the bottom right corner icon shown in the adjoining image.<br />
<br />
<br />
At present, these fields can only contain raw text. There are no formatting options (bold, italic, etc.) available.<br />
<br />
<div style="clear: both"></div><br />
<br />
===The Padlock Button and Organizing Elements===<br />
(aka. '''[[Character_Sheets#Repeating_Section|Repeating Section]]''')<br />
[[File:5E_OGL_Sheet_Padlock.gif|right|frame|The Padlock Toggle]]There is a <span style="font-family:Pictos;">(</span> (padlock) icon set at the bottom of several different fields of the '''D&D 5E by Roll20''' Sheet. It is used where a player is meant to add entries such as individual attacks, actions, pieces of equipment, features & traits, tool proficiences & custom skills, other proficiencies & languages, and spells. This icon behaves as a toggle button. <br />
<br />
When set in the <span style="font-family:Pictos;">(</span> locked position (default), a player can add new entries into the field. When the button is toggled to <span style="font-family:Pictos;">)</span>(unlocked), a player can no longer add new entries, but they will be able to reorder or delete any of the existing ones. The <span style="font-family:Pictos;">#</span>(red trash bin)-icon overlaid on the right hand side of the entry will delete it.<br />
<br />
{{Ambox<br />
|nocat=true<br />
| type = content<br />
| text = '''Deleting an entry cannot be undone!''' On left side of every entry while the padlock is <span style="font-family:Pictos;">)</span> unlocked is a re-sort icon symbolized by '''<big>≡</big>'''(three parallel lines). By clicking and dragging on this icon, you can rearrange the order of the entries in the field.<br />
}}<br />
<br />
{{Ambox<br />
|nocat=true<br />
| type = content<br />
| text = Some of the features of '''Repeating Sections''' do not work when the [[Character_Sheets#Character_Sheet_in_a_separate_window|Character Sheet is in a separate window]].<br />
}}<br />
<br />
<br />
<div style="clear: both"></div><br />
<br />
==Utilizing the 5th Edition SRD Compendium==<br />
[[File:5E_OGL_Sheet_Compendium.png|right|The Compendium Tab]]Upon adding the D&D 5E by Roll20 Character Sheet to a campaign, the [https://app.roll20.net/compendium/dnd5e/BookIndex| 5th Edition SRD Compendium] is automatically enabled for use from it's own <span style="font-family:Pictos;">i</span> [[Compendium]]-tab in the '''[[Sidebar]]''' of the application. It's located between the {{Journal}} and <span style="font-family:Pictos Custom;">u</span> [[Jukebox]]-tabs, and is accessible for both GM and Player alike.<br />
<br />
<br />
The <span style="font-family:Pictos;">i</span> [[Compendium]] allows for rapid searching of all rules, classes, monsters, spells, items, and more that are included in the 5th Edition SRD. This minimizes time spent for the gaming group to leaf through a book in the middle of a session for a rule clarification. Even better, both the GM and the Player can utilize dragging and dropping* from the <span style="font-family:Pictos;">i</span> [[Compendium]]-tab directly to your character sheets. This makes statting NPCs and PCs far faster than inputing everything manually.<br />
<br />
{{mbox | text = '''NOTE:''' The 5th Edition SRD is similar but NOT identical to the ''Dungeons and Dragons'' 5th Edition Rule Book. Some skills, classes, creatures, items, and other elements found within the ''Dungeons and Dragons'' rule book are strictly intellectual property of Wizards of the Coast and not accessible through their Open-Game License(OGL).}}<br />
<br />
<br />
===Statting PCs===<br />
Dragging from the <span style="font-family:Pictos;">i</span> [[Compendium]] works for the Equipment and Spell fields of the PC Sheet. This will not only carry over the name of the item or spell, but the relevant attack and damage rolls and any rules or flavor text that comes with it. Adding Compendium items in this fashion also automatically adds the equipment item (if it's a weapon) or spell to the Attacks & Spellcasting field to roll directly from. Items that modify a character's Attributes, Saves, AC, To Hit, Damage, Spell Attacks, and Spell DC will be automatically calculated on the sheet when dragged in. For example, if a Belt of Giant Strength is dragged to a sheet, the strength Attribute Score will become highlighted in blue and its attribute score will be increased. An asterisk is appended to the right of the score to also signify that it has been modified by an item. When you mouse over this number, the strength Attribute Score will revert back to what its unmodified total so you can refer back to it. Dropping a Compendium items that is an ammunition type (arrows, crossbow bolts, blowgun darts, etc) will automatically fill out a resource field for that item and link it to its entry in the Equipment section.<br />
<br />
To insert a Compendium item into the character sheet, run a search for the Item or Spell you want to add in the <span style="font-family:Pictos;">i</span> [[Compendium]]-tab. Once found, click and drag on the Compendium item's name so that it creates a little named tile that follows along with your mouse. Drag this over to the character sheet, it doesn't matter where. A text box that reads, "ACCEPTING DROP FROM COMPENDIUM" will appear on your sheet if this is done correctly. Let go of the tile and the entry will be auto-completed with all the data pertaining to the the Compendium entry in the correct location on the sheet. You can see this in action below under [[#Equipment|Equipment]].<br />
<br />
===Statting NPCs===<br />
You can fill out an entire NPC sheet in a single drag and drop. Run a search for the NPC you want to create from the <span style="font-family:Pictos;">i</span> [[Compendium]]-tab. Once found, click and drag on the NPC name so that it creates a little named tile that follows along with your mouse. Drag this to anywhere over the Tabletop area of the screen. Let go of the tile and a new character journal will be created named after the NPC from the Compendium entry. Its sheet will be changed over to the NPC sheet and filled with the entire NPC entry from the Compendium including their Actions, Reactions, and Legendary Actions if applicable. If you're using one of the Compendium expansions bought from the Roll20 Marketplace like the Monster Manual or Volo's Guide to Monsters, token art will also be pulled from the Compendium entry, placed on the table, and linked to your NPC's journal.<br />
<br />
You can also drag an NPC entry from the Compendium to an existing journal entry if you have the sheet open. If the sheet is in PC sheet mode, it will automatically change it over to the NPC sheet, and add its entry elements to it.<br />
<br />
One thing to note about dragging a stat block over from the Compendium is that it uses an ''additive'' behavior. It will not replace anything that you have already entered manually.<br />
<br />
=The PC Sheet=<br />
The '''D&D 5E by Roll20 Sheet''' contains both the PC Sheet ''and'' the NPC Sheet. By default, a new character journal is set to the PC sheet, but you can switch between the two by toggling it from the [[#Settings Page|General Options Settings]]. The PC Sheet is split up into four pages and can be selected from the buttons just underneath the header at the top of the sheet. They are listed from left to right order: The [[#Core Page|Core Page]], The [[#Bio Page|Bio Page]], The [[#Spells Page|Spells Page]], and The [[#Setting Page|Setting Page]].<br />
<br />
== Creating and Leveling up a character with Charactermancer ==<br />
Players and GMs using the '''D&D 5E by Roll20''' Sheet can use the Charactermancer to create and level up characters.<br />
<br />
'''How to use the Charactermancer for [[Charactermancer (D&D Fifth Edition)|character creation and leveling]].'''<br />
<br />
<br />
{{Ambox<br />
|nocat=true<br />
| type = content<br />
| text = The Charactermancer do not work when the [[Character_Sheets#Character_Sheet_in_a_separate_window|Character Sheet is in a separate window]].<br />
}}<br />
<br />
==Core Page==<br />
[[File:5E_OGL_PC_Core_Guide.jpg|right|frame|The Core Page]]The Core Page is selected by default and has most of the information you'll want to use on a regular basis to play your character. This should look very similar to the content you would normally find on the first sheet of the physical "D&D 5E by Roll20" player character sheet. The screenshot at the top of this wiki page displays the entirety of the Core Page. <br />
===(1) Core Header===<br />
[[File:D&D5E-Roll20-core-header.png|550px]]<br />
<br />
The header block at the top of the sheet changes based on the page you have selected. On the Core page you can select a class by its dropdown menu. The available options from the dropdown are: Barbarian, Bard, Cleric, Druid, Fighter, Monk, Paladin, Ranger, Rogue, Sorcerer, Warlock, and Wizard. You can create a custom class from the Settings Page.<br />
<br />
Once a class has been selected you can update the class's level by changing the number next to the class. The sheet will also automatically mark the abilities that class has proficiency in as well as automatically select the dice that will be used when Hit Dice are rolled. You can change the Hit Dice setting manually from the options menu. If your character multi-classes, then the secondary class and its level will appear beside the primary class. This Class and Level field can hold up to four classes if desired.<br />
<br />
The fields for Background, Race, Alignment, and Experience Points allow you to fill in whatever text you wish to put in them. The Character Name persists over all pages of the sheet and is tied to the name you give to the journal entry. Changing it on the sheet itself will also change the name on the character journal and vice versa once it is closed.<br />
<br />
===(2) Attributes===<br />
<br />
[[File:5E_OGL_Sheet_Attribute_Block.jpg|left]]Along the left side of the sheet are listed the 6 primary attributes: Strength, Dexterity, Constitution, Intelligence, Wisdom, and Charisma. These attributes are used by almost every other calculation on the sheet, as they are the core definition of a character. Each attribute block has the core attribute score, which can be changed by modifying the number in the oval at the bottom of each block, and, inside the square, the attribute modifier which is auto-calculated based on the score below it. All racial ability score increases must be manually added to the core attribute score using the settings "gear" symbol at the top of the page (where the Core, Bio, and Spells buttons are located.) The attribute modifier uses the following calculation to set the value:<br />
<br />
<br />
<code>[[floor((@{strength}-10)/2)]]</code><br />
<br />
The attribute can be referenced by its name, such as @{dexterity} while the attributes modifier can be referenced by adding the mod suffix, @{dexterity_mod}.<br />
<br />
<div style="clear: both"></div><br />
<br />
===(3) Inspiration===<br />
<br />
[[File:D&D5E-Roll20-inspiration.png|left]]You can track whether or not you have Inspiration by clicking the circle next to the Inspiration block at the top left of the Core page. This will toggle a dragon spiral icon on and off for indication purposes.<br />
<br />
<div style="clear: both"></div><br />
<br />
===(4) Proficiency Bonus===<br />
<br />
[[File:5E_OGL_Sheet_Proficiency.png|left]]Your character's proficiency bonus is listed near the top left of the page. You cannot modify this value manually, instead it is automatically set based off your character's over-all level. Your character's Level can be set by changing the number next to your Class name in the [[#header_info|Header]] at the top when on the Core page.<br />
<br />
<div style="clear: both"></div><br />
<br />
===(5) Saving Throws===<br />
<br />
[[File:5E_OGL_Sheet_Saving_Throws.png|left]]Next to the core Attributes on the left side of the page is a list of the same attributes to be used in making saving throws. To mark an attribute that your character has proficiency in for saving throws, check the box next to the appropriate attributes. When you select a class in the header section of the Core page it will automatically check the correct boxes for that class's proficiencies.<br />
<br />
You can add an additional field to Saving Throws to serve as a Global Save Modifier. An example is if the character is under the influence of the Bless spell and can roll a 1d4 in addition to the result of their saving throws. This is enabled from the Settings Page under General Options. Once enabled a seventh checkbox and field will be added at the bottom of the Saving Throws block with a text field to enter the additional die roll. For this example, you could enter "1d4[BLESS]" in the global checkbox's text field that you can enable when the character is under the effects of the Bless spell. The word between the brackets becomes a label that can be seen when you mouse over the roll result in chat. While this Global Save Modifier is checked, every roll made from the Saving Throws block and performing a Death Save will add this modifier to the result.<br />
<br />
<div style="clear: both"></div><br />
<br />
===(6) Skills===<br />
[[File:5E_OGL_Sheet_Skills.png|left]]<br />
To the right of the Core Attributes is a list of all of the character's Skills. Each skill can be rolled by clicking on the skill name. If you have proficiency in a specific skill, then you would check the box next to the skill name, this will automatically add your proficiency bonus to that skill's checks. Each skill also lists the core attribute, that is used in the roll calculations, next to it in parenthesis.<br />
<br />
You can set advanced skill options for the Settings page, such as skill expertise, flat bonuses from class archetypes or feats, as well as Jack of All Trades.<br />
<br />
<div style="clear: both"></div><br />
<br />
===(7) Armor Class, Initiative, & Speed===<br />
<br />
[[File:D&D5E-Roll20-AC-Init-Speed.png|left]]The Armor Class & Speed blocks at the top center of the page can be used to keep track of your Armor and Speed values. The Initiative block cannot be modified manually, but instead is auto-calculated based off your character's Dexterity. If you have any additional initiative modifiers you can add them on the {{gear}} [[#Settings Page|Settings Page]] under Initiative Modifier in the Class Options block.<br />
<br />
Armor Class can also be tracked automatically by using the [https://app.roll20.net/compendium/dnd5e/BookIndex Compendium] compatible inventory, on by default.<br />
<br />
You can configure a custom AC calculation using the {{gear}} [[#Settings Page|Settings Page]] under the Attribute Tracking section. It's listed as "Armor Class Tracking" and is set to "Automatic" by default. If you select Custom, you can select up to two different attributes to apply to the character's armor class.<br />
<div style="clear: both"></div><br />
<br />
====Using the Global AC Modifiers====<br />
If you check the "Show Global AC Modifier" field in the character sheet General Options settings, the sheet will display a repeating section to configure and apply different modifiers to AC. So, for example, if your character has a common bonus, such as from a spell or a conditional feat or fighting style, you can toggle that AC bonus from the character sheet directly.<br />
<br />
====Rolling for Initiative and the Turn Order Tracker====<br />
Clicking on the word INITIATIVE will roll that character's initiative score. If your players have [[Token|tokens]] linked to their character sheets, they can roll their initiative ''and'' simultaneously add their character and its initiative score to the {{Turn Tracker}} automatically. What is required of the player is that their linked token must be currently selected on the Tabletop before they roll off their sheet.<br />
<br />
If you would like to enable a tie breaker component to Initiative, there is an option to enable this from the [[#Settings Page|Settings Page]] under the "Attribute Options" block. What this does is that it will add your dexterity Attribute Score as a decimal value to your Initiative. So if you have a character with a dexterity attribute score of 14, your initiative modifier will change from a <code>2</code> to a <code>2.14</code>.<br />
<br />
===(8) Hit Points & Temporary Hit Points===<br />
[[File:5E_OGL_Sheet_HP.png|left]]The Current Hit Points and Temporary Hit Points blocks are used to keep track of your character's Hit Points (HP). Inside the Current Hit Points block, at the top, is a line that lists the character's maximum amount of HP. <br />
<br />
<br />
When your character takes damage, if they have any, it should be subtracted from their Temporary Hit Points first, then any remaining damage would then come off of the character's Current Hit Points.<br />
<br />
<div style="clear: both"></div><br />
<br />
===(9) Hit Dice===<br />
[[File:5E_OGL_Sheet_Hit_Dice2.png|left]] The Hit Dice block is used to keep track of and roll your character's hit dice. Inside the Hit Dice block, at the top, is a line to keep track of the total number of dice your character can have. In the main area of the block you would keep track of the remaining hit dice. Clicking the "HIT DICE" label will roll the hit dice for your selected class automatically. If you wish to change the dice that is rolled you can do so in the Class Options section of the [[#Settings Page|Settings Page]] ({{gear}} icon). <br />
<br />
<br />
If your character is multi-classed, when rolling your hit dice (by clicking "''HIT DICE''", a pop-up will ask which of your character's current class's hit dice you want to roll. This input accepts only numerals a input to make automatic tracking of the [[API:A Guide to the API|API]] possible.<br />
<div style="clear: both"></div><br />
<br />
===(10) Death Saves===<br />
[[File:5E_OGL_Sheet_Death_Saves.png|left]]The Death Saves block is used to keep track of your character's death save rolls once they have been knocked out. You can click the "DEATH SAVES" label to make a death save roll. If you roll greater than 10 you would check one of the boxes next to "Successes" otherwise you would check a box next to "Failures". If your character has any modifiers to their death save rolls they can be added in the Class Options section of the Settings Page(gear icon).<br />
<div style="clear: both"></div><br />
<br />
===(11) Attacks & Spellcasting===<br />
[[File:5E_OGL_Sheet_Attacks_And_Spellcasting.png|left]]The Attacks & Spellcasting block in the center of the Core page of this character sheet will be one of the most often used sections. To start, you can manually add any attack or spell to this section by hovering over the block and clicking the "Add" button(the <span style="font-family:Pictos;">&</span> symbol). This will open a form that can be filled out with all of the information about the specific attack or spell you are adding. <br />
<br />
<br />
This section will automatically add attacks, with all the stats, for spells that have an attack component when they are added to your spell sheet on the [[#Spells Page|Spells Page]]. This happen both if you add the spell manually or if you drag and drop a spell from the <span style="font-family:Pictos;">i</span> [[Compendium]]. An attack is also automatically created if you drag and drop an item from the Compendium into your sheet.<br />
<br />
<div style="clear: both"></div><br />
[[File:Poisoned Dagger 5e Attack.png|right|frame|An example of an attack form filled out for a physical attack using a +1 Poisoned Dagger]]For example, lets say Erin the Bold has a +1 Poisoned Dagger that has the stats of a regular dagger, but also metes out an additional 1d6 of poison damage alongside the typical 1d4 points of piercing damage. The image displayed to the right is how the attack would be set up:<br />
<br />
<br />
Since this is a [https://app.roll20.net/compendium/dnd5e/Items:Dagger#h-Dagger dagger], and daggers have the "[https://app.roll20.net/compendium/dnd5e/Weapons#h-Weapons Finesse]" attribute I can chose either STR or DEX for my bonus attribute. Erin is quicker than she is strong, so we will pick DEX as the attribute to attack with, as well as checking the "proficient" checkbox since Erin is experienced with using these sorts of weapons. She doesn't have any other gear that might make her attacks better, so we will leave the generic bonus between the attribute and proficiency blank, or 0. Being a +1 Poisoned Dagger means that it is also magical, so it gets a 1 in the magic bonus slot just below. A dagger can also be used as a thrown weapon, so we've added the weapon's throwing range info to the "Range" field. Since a weapon does damage, we have checked the first "Damage" checkbox and filled in the required fields. This dagger does 1d4 piercing damage + Erin's DEX mod + 0 bonus damage (this would be used for bonus damage on top of the magical +1) and it doesn't have anything to change the critical damage so we just put the same damage into the "crit" box. Because this dagger can also cause poison damage, we also check the second "Damage" checkbox and fill in the info for the 2nd set of damage. The poison does a flat 1d6 poison with no extra bonuses, so we've selected "-" to say there is no attribute that adds to this damage. This damage also doesn't have anything to make the crit different so we set that to 1d6 as well. There are no extra saving throws or effects that are included with this attack, so we leave these additional sections blank. <br />
<br />
These additional effect sections will be used more commonly with spells, like [https://app.roll20.net/compendium/dnd5e/Fireball#h-Fireball Fireball], where you would require a DEX save against your SPELL DC, which will be set according to your character's spell casting level. For a fireball, the save effect would be "half damage" and the "Description" would be something like "Hits all creatures within 20 ft of the explosion point".<br />
<br />
After you are done modifying all of individual stats for an attack you can click the gear icon at the top right of that section and it will hide the stats for that attack. If ever you need to change these stats in the future you can hover over the entry and click the <span style="font-family:Pictos;">y</span>(gear)-icon that shows up to unhide the stats section. <br />
<br />
<div style="clear: both"></div><br />
====Adding Global Attack and Damage Modifier====<br />
You can add two special entries to the Attacks & Spellcasting block to handle to global Attacks and Damage modifications to rolls. An example is if the character is under the influence of the Bless spell and can roll a 1d4 in addition to the result of their attack roll. This is enabled from the [[#Settings Page|Settings Page]] under General Options. Once enabled, a checkbox will be added at the bottom of the Attacks & Spellcasting block with a text field to enter the additional die roll. For this example, you could enter <nowiki>"1d4[BLESS]"</nowiki> in the global checkbox's text field that you can enable when the character is under the effects of the Bless spell. The word between the brackets becomes a label that can be seen when you mouse over the roll result in chat. While these Global Modifiers are checked, every roll made from the Attacks & Spellcasting block will add these modifiers to the result.<br />
<br />
====Rolling from the Attacks & Spellcasting Block====<br />
[[File:Poisoned Dagger 5e Roll.png|frame|An attack roll from a +1 Poisoned Dagger]]Rolling from the Attacks & Spellcasting Block is no different than rolling from any other portions of the character sheet. Hovering your mouse over any entry here will highlight its entire label (NAME, ATK, and DAMAGE/TYPE) in red and you'll be able to click on it to roll the attack or spell. You can also drag this entry into the Macro Bar to give yourself easy access to this attack. Because this is a repeating section, the macro name will be a bit messy, but you can right-click the button and rename the macro to whatever you like.<br />
<br />
With any attack that checks for AC, you will see TWO rolls set side by side for the Armor Class check with the name of the attack listed underneath them with the Attack modifier bonus (ATK) appended to the Attack name in light grey. The Roll20 D&D 5E Character Sheet ''always'' rolls for Advantage by default, so you will always have two roll results for this check (most gaming groups use the left roll result if neither Advantage or Disadvantage is being factored in the check). If there is a specified range for the attack, this will be listed above the attack's name.<br />
<br />
Underneath the AC Check and Attack Name is the Damage roll result for the attack. Underneath this roll result will be the Damage Type (ex. slashing, piercing, poison, fire, etc.) listed in light grey italicized font.<br />
<br />
For spells that don't check for AC and instead require a Saving Throws to mitigate or negate the spell's effect, the SPELL DC is listed first. Underneath this, in italicized font, is the effect if a character succeeds the check listed. Underneath the effect is the required attribute saving throw that must be rolled. If Damage is applied, this result is rolled and listed next with its Damage Type.<br />
<br />
[[File:5e_attack_example.gif|right|frame|How to view attack damage when the sheet is set to "Don't Auto Roll Damage"]]<br /><br />
<br />
<br />
{{mbox | text = '''NOTE:''' If your character sheet's Settings have "Auto Damage Roll" set to "Don't Auto Roll Damage" under General Options, the damage will not be listed underneath the AC roll result in chat. The damage was rolled, but presently hidden from view. Anyone can see the damage delivered by manually unfolding the roll result open by hovering your mouse over the roll result in chat and clicking on the attack/spell's name.}}<br />
<div style="clear: both"></div><br />
<br />
===(12) Personality Traits, Ideals, Bonds, and Flaws===<br />
These text fields lock to prevent accidental edits. When a sheet is first created, these fields are unlocked and given a dashed yellow border to the top of the field to showcase that they're editable. To lock the field after entering text, click on the gear icon in the upper right corner of the field. This will remove the yellow border and the field will conform in height to display everything within it.<br />
<br />
There presently isn't a means to format the raw text (italicize, bold, font alignment, etc) within these fields and any line breaks are stripped out. If you ever need to edit the content again while the field is locked, mouse over the desired field and the gear icon will reappear in the top right. Clicking on that will unlock the field once again for edits.<br />
<br />
===(13) Class & Other Resources===<br />
[[File:5E_OGL_Sheet_Resources.png]]<br />
<br />
The Class & Other Resource Blocks can be used to keep track of either an item quantity you have in your equipment (like arrows in a quiver), or skills that don't fit into the other sections on the sheet (like a '''Sorcerer's Sorcery Points''', a '''Cleric's Channel Divinity''' at higher levels, or the number of rounds a '''Barbarian''' has been '''Raging''' so far in a combat encounter).<br />
<br />
There are 3 fields per Block:<br />
* Resource Max:<br />
** The Resource Max field is a text box which allows you to quantify exactly what you're tracking (ex. "Total: 10 Rounds").<br />
* Resource:<br />
** The Resource field is a numeral that you dial up or down or input directly.<br />
* Resource Name:<br />
** The Resource Name is a text box that allows you to label the resource when you click on the light grey "OTHER RESOURCE" label to overwrite it with your own.<br />
**"OTHER RESOURCE" is placeholder text<br />
<br />
<br />
A resource block will be filled automatically if you checkmark an Equipment item as "USE AS A RESOURCE" & the Item Quantity field will be paired with the Resource field in the Resource block & vice versa (you'll need to click outside of the field or hit Enter for changes to refresh across the sheet). If the two resource blocks given by default are not enough then you can add additional blocks by hovering over the section & clicking the "Add" (+ symbol) button.<br />
<br />
The Item Name will also be added to the Resource Name field, however the Resource Max field is apparently not linked to the Item currently.<br />
<br />
If you drag & drop an ammunition item type from the Compendium into your character sheet, the item is added to the Equipment block & is automatically listed & linked as an Other Resource.<br />
<div style="clear: both"></div><br />
To call the first set of class resources use:<br />
* Class Resource <code>@{class_resource}</code><br />
* Other Resource <code>@{other_resource}</code><br />
<br />
<br />
To call the Repeating resources use<br />
* Repeating Resource 1st left<code>@{repeating_resource_$0_resource_left}</code><br />
* Repeating Resource 1st right<code>@{repeating_resource_$0_resource_right}</code><br />
* Repeating Resource 2nd left<code>@{repeating_resource_$1_resource_left}</code><br />
* Repeating Resource 2nd right<code>@{repeating_resource_$1_resource_right}</code><br />
* etc.<br />
<br />
<br />
If you want to do a basic Full Readout of the Repeating Resource, the Format would be (Top Left to Bottom Right):<br />
* Class: <code>@{class_resource_name}: @{class_resource} / @{class_resource|max}</code><br />
* Other: <code>@{other_resource_name}: @{other_resource} / @{other_resource|max}</code><br />
* Left 0: <code>@{repeating_resource_$0_resource_left_name}: @{repeating_resource_$0_resource_left} / @{repeating_resource_$0_resource_left|max}</code><br />
* Right 0: <code>@{repeating_resource_$0_resource_right_name}: @{repeating_resource_$0_resource_right} / @{repeating_resource_$0_resource_right|max}</code><br />
* Left 1: <code>@{repeating_resource_$1_resource_left_name}: @{repeating_resource_$1_resource_left} / @{repeating_resource_$1_resource_left|max}</code><br />
* Right 1: <code>@{repeating_resource_$1_resource_right_name}: @{repeating_resource_$1_resource_right} / @{repeating_resource_$1_resource_right|max}</code><br />
* etc.<br />
<br />
===(14) Tool Proficiencies===<br />
[[File:5E_OGL_Sheet_Tool_Proficiencies.png|left]]The Tool Proficiencies block is for listing a character's Tool Proficiency skills. At the bottom of this block is an "Add" (<span style="font-family:Pictos;">&</span> symbol) button. Clicking this will add a new entry to this block where you can add all of the relative stats for a specific tool proficiency, say Woodcarver's Tools. You can set the level of proficiency to either Proficient, Expertise, or Jack of All Trades. The roll bonus for that tool will reflect the proficiency level selected. Next is an Attribute drop down menu where you can select which character attribute to roll with for a proficiency check. One of the options you can choose is "QUERY ATTRIBUTE" which when you click on the Tool Proficiency to roll it, you will be prompted to choose which attribute you would like to use. The attribute used for the check will be up to the GM when it is time to make the roll check. If there is any additional bonus modifiers that come along with the tool in question, you can input it in the "MODS:" field.<br />
<br />
Once you finished filling out the stats for this tool you can click the <span style="font-family:Pictos;">y</span>(gear) icon at the top right of the entry to hide the stat fields and leaving behind just the rollable button. You can roll by either clicking on this rollable button or dragging it to your [[Macro Bar]].<br />
<br />
You can also use this section to create custom skills or rolls for your campaign setting or home-brew ruleset. Check out the [[#Custom Skills and Stats|Advanced Use]] section for further details.<br />
<br />
====Global Skill Modifier====<br />
You can add a special entry to the Tool Proficiencies & Custom Skills block to handle to global Attacks and Damage modifications to rolls. An example is if the character is under the influence of the Guidance spell and can roll a 1d4 in addition to the result of their skill check. This feature is enabled from the [[#Settings Page|Settings Page]] under General Options. Once enabled, a checkbox will be added at the bottom of the Tool Proficiences & Custom Skills block with a text field to enter the additional die roll.<br />
<br />
For this example, you could enter "1d4[Guidance]" in the global checkbox's text field that you can enable when the character is under the effects of the Guidance spell. The word between the brackets becomes a label that can be seen when you mouse over the roll result in chat. While this Global Modifier is checked, every roll made from the Tool Proficiencies & Custom Skills block and the Skills block will add this modifier to the result.<br />
<div style="clear: both"></div><br />
<br />
===(15) Other Proficiencies & Languages===<br />
[[File:5E OGL Sheet Proficiencies.png|left]]<br />
This block can be set up to be Compendium Compatible (where you can add repeating sections for individual items) or as one resizable free-text field to enter whatever you wish in here. If you don't feel the Tool Proficiency block is needed (as in, you don't feel like your party will ever have to roll individual tool sets), you can store a character's Tool Proficiencies here instead. There presently isn't a means to format the raw text (italicize, bold, font alignment, etc). You can adjust this block's behavior by going to the Settings Page of the sheet and going to the General Options block to change whether this block uses the Simple or Compendium Compatible layout.<br />
<br />
When the Other Proficiences & Languages block is made Compendium Compatible, each repeating field lists a Type selection field and a Proficiency text field. Type has the following options available from its drop down selection menu: Language, Weapon, Armor, Other. <br />
<p style="clear:both;"></p><br />
<br />
===(16) Equipment===<br />
[[File:5E OGL Sheet Equipment.png|framed|right|The Equipment block of the PC Sheet]]<br />
The Equipment block at the bottom of the page has 2 different versions: a Simple version that features a single plain text field where you can track all of your equipment in any format you wish and a Compendium Compatible version that allows you to drag and drop items from the Compendium to automatically populate repeated sections for each indivdual piece of equipment.<br />
<br />
To swap between the two different Equipment block versions, first, go to the sheet's Settings Page (gear icon at the top right of the page) and then to the "General Options" section. Here, on the field labeled "Inventory", you can select between "Simple" or "Compendium Compatible" respectively. Like the name implies, if you want to be able to copy items directly from the Compendium using drag and drop, you must use the Compendium Compatible version. Dragging item entries from the Compendium to the character sheet will add it fully filled in the Equipment section as well as other automated actions described below.<br />
<br />
====Automated Compendium Functionality====<br />
If you populate the Equipment block by dragging and dropping <span style="font-family:Pictos;">i</span> [[Compendium]] items, there are several automatic features that occur when the entries you drag in our equipment items.<br />
Auto-Equip: Every item dragged to the sheet is automatically equipped in the Equipment Section<br />
*'''Weapons:''' A weapon dragged in from the Compendium will add an attack in the Attacks and Spellcasting section for that item.<br />
*'''Armor:''' Armor that is dragged in from the Compendium will add its bonus to the Armor Class (while equipped) section. If you drag multiple pieces of armor to the same sheet and at least two armor entries are equipped at once, a warning will pop up in red at the top of the Equipment Block that the Armor Class isn't being correctly calculated because of the bonus overlap. This warning will dissapear when you unequip down to a single set of armor.<br />
*'''Magical/Wondrous Items:''' Items that modify Attributes, Saves, AC, To Hit, Damage, Spell Attacks, and Spell DC will add that bonus to those elements on the sheet. In most cases, the attribute that is being modified will highlight in blue and followed with an asterisk to showcase that the attribute is being modified by an item. Mousing over the modified number will display the base value of that attribute before the item's modification is applied. This stat modification only applies if the item is equipped in the Equipment section and it will remove its bonus if it is unequipped.<br />
*'''Ammunition:''' Items dragged in from the Compendium that are used for ammunition such as arrows, bolts, darts, and slingstones, will automatically populate and link to an Other Resource field.<br />
<br />
====Manually Adding Items====<br />
You can also add items manually by hovering over the block and clicking the "Add" button (+ symbol). Each equipment entry, by default, show fields for quantity, name, and weight of an item. If you hover over a row and click the small "information" icon (grey-filled circle with a lowercase i centered in it) that appears at the bottom right of the entry you can also set some additional features. <br />
<br />
*'''Equipped Checkbox:''' The checkbox changes the appearance of the Item Name so it's easier to tell what your character currently has equipped from a glance. When left unchecked, the Item Name's font turns grey. When checked, the Item Name becomes a solid black.<br />
*Use As A Resource Checkbox: When checked, this will enable one of the Class Resource blocks and list the item name and its quantity within it. The quantity is tied between the two so changing it in one will be reflected in the other field after clicking outside the field.<br />
*'''PROP:''' This is a text field where you would take note of weapon properties such as ''finesse'', ''versatile'', or ''light''.<br />
*'''MODS:''' This is a text field where you would take note if an item (likely magical) would modify your stats in some fashion such as a character's Attributes, Saves, Skills, AC, To Hit, Damage, Spell Attacks, and Spell DC. If a stat is modified here, its attribute value will become highlighted in blue and adjusted by the supplied modifier listed here. An asterisk is appended to the right of the value to also signify that it has been modified by an item. While your mouse is hovering over the attribute, it will revert back to its unmodified total so you can refer back to its pre-moddified value.<br />
**The format for a stat modification is ''stat name:n'' where n is the stat bonus (ex. ''Strength:21'')<br />
*'''Description Field:''' This is a simple text field to include a description of the particular item and of any special qualities or effects it might have on the player.<br />
Some if not all of these fields will be filled in automatically when adding from the Compendium (where applicable).<br />
<br />
Both versions of the equipment field have the sections for each of the [https://app.roll20.net/compendium/dnd5e/Treasure#h-Treasure coins] you may find on your adventures: copper(CP), silver(SP), electrum(EP), gold(GP), and platinum(PP).<br />
<br />
====Encumbrance====<br />
If you are following Encumbrance rules, the <span style="font-family:Pictos;">i</span> [[Compendium|Compendium Compatible]] Equipment block will automatically calculate and track the weight of your character's backpack if you enter the weight values for any of the items in your Equipment list. When your character becomes encumbered, and depending on its severity, the words ENCUMBERED, HEAVILY ENCUMBERED, or IMMOBILE will display in red underneath the TOTAL WEIGHT value. You can also choose to follow Simple, Variant Encumbrance rules, or not follow Encumbrance rules at all by toggling it off on the [[D&D 5E by Roll20#Settings Page|Settings Page]] under "General Options".<br />
<br />
====Mods====<br />
The Mods field of each piece of equipment can modify the values of ability scores, AC, saving throws, Skill (Ability) checks and more. What follows is a list of the modifiers, and the proper syntax for adding them.<br />
<br />
All modifiers are separated by commas. There are other modifiers that can appear the mod field, used in creating the item from a compendium drag and drop operation, but the modifiers below have live effects on the character sheet, depending on if the item is marked as “equipped”.<br />
<br />
'''replace the <code>+n</code>, with the number you want.''' For example, if you want to boost Animal Handling skill by 3, you look at the table and find <code>Animal Handling +n</code>, so you will add to your item <code>Animal Handling +3</code>.<br />
<br />
{| class="wikitable" <br />
|-<br />
! Modifier<br /><br />
! Effect<br /><br />
|-<br />
| style="width: 20%;" | '''Combat Modifiers'''<br />
| '''These affect items that provide attacks (Appear in the attack section of the character sheet)'''<br />
|-<br />
| Melee Attacks +n<br />
| Adds +n hit "Magic Bonus" to that attack. It is not global, and only affects a weapon(melee or ranged), not an item, staff or other category. The bonus is figured into the attacks display on the 5e sheet.<br />It is NOT ''Melee Attack''.<br />
|-<br />
| Melee Damage +n<br />
| Adds +n damage "Magic Bonus" to that attack. It is not global, and only affects a weapon(melee or ranged), not an item, staff or other category. The bonus is listed separately in the attacks display on the 5e sheet.<br />
|-<br />
| Spell Attack +n<br />
| Adds a global +n to the character's Spell Attack bonus.<br />It is NOT ''Spell Attacks.''<br />
|-<br />
| '''Saving Throws'''<br />
| '''All modifiers stack with “Saving Throws +n'''<br />
|-<br />
| Strength Save +n,<br />Dexterity Save +n,<br />Constitution Save +n,<br />Intelligence Save +n,<br />Wisdom Save +n,<br />Charisma Save +n<br />
| Adds a +n to the indicated saving throw<br />''Do not use a colon.''<br />
|-<br />
| Saving Throws +n<br />
| Adds a Global Modifier to ALL saving throws.<br />
|-<br />
| Spell DC +n<br />
| Adds a global +n to a spell casting character’s Spell Save DC.<br />It is NOT Spell ''Save'' DC.<br />
|-<br />
| '''Ability Scores'''<br />
| <br />
|-<br />
| Strength +n,<br />Dexterity +n,<br />Constitution +n,<br />Intelligence +n,<br />Wisdom +n,<br />Charisma +n<br />
| Provides a bonus to the indicated ability score, which will appear in blue on the sheet while the bonus is active.<br />Do not use a colon. ''Strength: +10'' will do nothing<br />
|-<br />
| Strength n,<br />Dexterity n,<br />Constitution n,<br />Intelligence n,<br />Wisdom n,<br />Charisma n<br />
| Replaces the indicated ability score, which will appear in blue on the sheet while the bonus is active.<br />Do not use a colon. ''Strength: 10'' will do nothing<br />
|-<br />
| '''Skills'''<br />
| <br />
|-<br />
| Acrobatics +n,<br />Animal Handling +n,<br />Arcana +n,<br />Athletics +n,<br />Deception +n,<br />History +n,<br />Insight +n,<br />Intimidation +n,<br />Investigation +n,<br />Medicine +n,<br />Nature +n,<br />Perception +n,<br />Performance +n,<br />Persuasion +n,<br />Religion +n,<br />Sleight of Hand +n,<br />Stealth +n,<br />Survival +n<br />
| Adds the value to the indicated Skill roll. Note that in this case, the <code>+</code> and a colon are optional. <code>Acrobatics +5</code>, <code>Acrobatics 5</code>, <code>Acrobatics: +5</code>, <code>Acrobatics: 5</code> will all add <code>5</code> to the character’s Skill roll. For consistency and to guard against future functionality, it’s probably best to follow the format for ability scores, and use a plus sign with no comma: <code>Acrobatics +5</code>.<br />There is no Global Skill modifier<br />
|-<br />
| '''AC'''<br />
| <br />
|-<br />
| AC +n<br />
| By itself, <code>AC: 13</code> adds 13 to the character’s Armor Class. It does not replace it. <br /><br />If <code>Shield</code>, <code>Light Armor</code>, <code>Medium Armor</code>, or <code>Heavy Armor</code> is also in the mods field, it will change the calculation.<br />''<code>Light Armor, AC: 13</code>'' will give a formula of 13 + dex mod<br />''<code>Medium Armor, AC: 13</code>'' will give a formula of 13 + dex mod (max +2)<br />''<code>Heavy Armor, AC: 13</code>'' will give you flat AC 13<br />''Shield, AC: 13'' would add 13 to the your AC. The Shield keyword is superfluous in this case.<br />''<code>Shield, AC: 2</code>'' will just add 2 to the AC.<br />Finally, a bare modifier, such as for a Ring of Protection can just be written as <code>AC: +2</code> or <code>AC +1</code>.<br /><br />Shield or bare AC bonuses will stack with other armor mods on different items. You cannot equip multiple armors simultaneously, or have a custom armor equation on the settings tab and wear an armor. This will generate a flag.<br /><br />The + and a colon are semi-optional. <code>AC +5</code>, <code>AC: +5</code>, <code>AC: 5</code> will all work. However, <code>AC 5</code> will do nothing. For consistency and to guard against future functionality, it’s probably best to indicate a base AC as <code>AC: n</code> and a Shield as <code>AC +n</code>.<br />At this point, there is no way to differentiate between Ranged AC and Melee AC, though some magic items such as the ''Arrow Catching Shield'' make the distinction.<br />
|}<br />
<br />
<br />
<br />
<div style="clear: both"></div><br />
<br />
===(17) Features & Traits===<br />
[[File:5E OGL Sheet Features Traits.png|thumbnail|left|The Compendium Compatible itemized version of the Features & Traits section]]<br />
The '''Features and Traits '''-block is the place to store '''Class-''', '''Race-''' and '''Background Features''', '''Feats''', and other special notes about your character or of a certain piece of equipment or ability. When using the Charactermancer, the previously mentioned features appears in this section.<br />
<br />
This block can be set up to be <span style="font-family:Pictos;">i</span> [[Compendium|Compendium Compatible]] (where you can add repeating sections for individual items) or as one resizable free-text field to enter whatever you wish in here. You can adjust this block's behavior by going to the [[D&D 5E by Roll20#Settings Page|Settings Page]] of the sheet and going to the '''General Options'''-block to change whether this block uses the Simple or Compendium Compatible layout. <br />
<br />
When adding items to the Compendium Compatible version of this block, you have the <code>Name</code> field, a <code>Source</code>-field where you can choose between (Racial, Class, Feat, Background, or Other) , a <code>Source Type</code>-text field to describe the type, and then the multilined <code>Description</code>-textbox. Clicking on the <span style="font-family:Pictos;">y</span>(gear)-icon in the top right corner of the item will lock/unlock the item's editability. When locked down, a <span style="font-family:Pictos;">w</span>(chat bubble)-icon appears when you mouse over the feature/trait. Clicking on the <span style="font-family:Pictos;">w</span> will share this feature's description in the {{Text Chat}}.<br />
<br />
There presently isn't a means to format the raw text (italicize, bold, font alignment, etc) of the Simple version or in the Description section of either version of the Features & Traits block.<br />
<br />
You can drag-n-drop '''Feats''' from the compendium, even though they can't be selected in the Charactermancer on levelup.<br />
<br />
PC Features and Traits can be called using an ability roll:<br />
<code>%{selected|repeating_traits_$0_output}</code><br />
Simply increase the $0 value to access all Features and Traits listed on the character sheet, $1, $2, $3...<br />
<br />
<p style="clear:both;"></p><br />
<br />
==Bio Page==<br />
[[File:D&D5E-Roll20-BIO-tab.png|right|thumb|250px|The Bio Page of the PC Sheet]]The Bio page, opened by selecting "BIO" from the 4 buttons near the top right of the sheet, is comprised of free-form text fields that can be used to keep track of less "structured" information about your character. You can use this page to describe your character's appearance, keep track of who their allies are and what organizations they've worked for, and on this page is a section to supplement the inventory list, on the front page, with the "Treasure" section, where you can keep track of all the loot you find along your travels.<br />
===Bio Header===<br />
[[File:D&D5E-Roll20-Bio-header.png|550px]]<br /><br />
<br />
The header of the Bio page contains the basic run down of a character's physical appearance.<br />
*'''Character Name:''' This is carried over from every single PC Page and matches the character journal's name<br />
*'''Age:''' The character's current age<br />
*'''Size:''' The size classification for the race type (Medium for most cases)<br />
*'''Height:''' The character's height<br />
*'''Weight:''' The character's weight<br />
*'''Eyes:''' The character's eye color<br />
*'''Skin:''' The character's skin color<br />
*'''Hair:''' The character's hair color/style<br />
<br />
===Character Appearance===<br />
While the Bio Header describes the bare bone physical characteristics of a PC, this field is for fleshing out the visual peculiarities and/or cues of your character. Does you character have a piercing gaze? A stooped posture? Are they fancily dressed or are their clothes moth-eaten? In essence, this field is for everything and anything one would note about the character–from the equipment or garb they wear to how they comport themself.<br />
<br />
===Allies & Organization===<br />
This text field is for listing important or campaign relevant NPCs that the character may have a connection with. It's also for keeping track of faction allegiance. In the case of ''Dungeons & Dragons''' Forgotten Realms world, a PC could be a member of the Harpers or the Emerald Enclave, among other major factions who are all vying for power of the continent.<br />
<br />
===Character Backstory===<br />
This field is for listing your character's pre-campaign history, their relations, and the pertinent places they have been to in the past.<br />
<br />
===Additional Features & Traits===<br />
This text field is a continuation of the [[#.2817.29_Features_.26_Traits | Features & Traits]] section of the Core Page. The section on the Core Page is a good place for commonly utilized features of a character or briefly jotting down an abbreviated list. This field on the Bio page gives you more real estate to fully write down everything you need in whole.<br />
<br />
===Treasure===<br />
This text field is where you can list all the loot you've collected while searching bodies and delving through dungeons. Since much of these effects are transient and are likely to be used, given away, or sold to the highest bidder at the earliest opportunity, this may be preferable place to keep this list of items rather than adding them to the itemized Compendium Compatible Equipment section (if you have that version enabled).<br />
<br />
==Spell Page==<br />
[[File:D&D5E-Roll20-Spells-tab.png|right|thumb|400px|The Spell Page]]The Spell page, opened by selecting the "SPELLS" button from the four buttons near the top right of the sheet, is used to keep track of all of the powerful magics at your character's fingertips.<br />
<br />
===Spell Page Header===<br />
[[File:D&D5E-Roll20-Spells-header.png|550px]]On the Spells page Header you can set the ability modifier that will be used for casting spells. Selecting the Spellcasting Ability block will allow you to select an attribute from a dropdown, and this will be used in all relevant spell rolls. This attribute will be set automatically when you select a spell casting class. The next two blocks, the Save DC and Attack Bonus will be set automatically based on the class that is selected on the Core page.<br />
<br />
===Spellcasting Ability===<br />
The Spellcasting Ability modifier will automatically update, depending on the class you select on the Core page, to the correct ability modifier for your class. If, for some reason, you need to change this value you can click on the modifier listed in this section and it will give you a drop-down list of all available ability modifiers.<br />
<br />
===Spell Save DC & Attack===<br />
The Spell Save DC and Spell Attack Bonus sections cannot be changed manually, but are just a visual output of modifiers that will be happening behind the scenes. The Spell Attack Bonus is the number that will be added to all spell attack rolls, automatically.<br />
<br />
The Spell Save DC refers to the Save DC that enemies will have to beat when they are trying to dodge/resist your incoming spells. Say, Fred the Sorcerer casts Lightning bolt, and his Spell Save DC is 14. Any enemies hit by his attack will have to make a DEX save and try to beat 14. If they manage to beat the attack, then they are only grazed and take half of the damage. If they don't beat 14, then they take the full damage of the attack instead.<br />
<br />
===Spell Levels & Spells Per Day===<br />
The main section of the Spells page lists 10 sections, ranging from 0 to 9, representing the Cantrips (0) and spells level 1 - 9 where the level of the spell is listed in the triangle on the left of each section header. The number in the left square of the header represents the total number of Spell Slots, in other words, the maximum number of times a spell of this level can be cast in between long rests. This number will be set automatically depending on the level of your character, but can be modified by clicking the up or down arrow or just entering a number in the space provided. The number in the right-most box in the headers is the Slots Remaining value that can be used for you to keep track of the number of times you've cast a spell at this level.<br />
<br />
===Adding Spells===<br />
[[File:D&D5E-Roll20-Spells-Icons.png|framed|right]]<br />
When you drag spells from the <span style="font-family:Pictos;">i</span> [[Compendium]] to the sheet, a new spell entry will be added to the Spell Page under the appropriate level header. This will copy over all corresponding information linked to the spell, as well as creating an attack entry in the [[D%26D_5E_by_Roll20#.2811.29_Attacks_.26_Spellcasting|Attacks & Spellcasting]]-block on the "Core" page, if the spell can be used as an attack. The name of the spell will be listed to the left of the entry and to the right are icons for whether the spell is a Ritual (R), requires Concentration (C), and lists whether there is a Verbal (V), Somatic (S), or Material (M). There is also a circle at the far left of the entry that can be toggled to be filled in with red or left empty. This toggle represents spells that are Prepared for the day and are available for a player's convenience to help track this.<br />
<br />
You can manually add spells by selecting the <span style="font-family:Pictos;">&</span> under any of the Spell Level headings. This will present you with a blank template where you can enter all of the information about a spell. By default, the spell card only contains non-attack information about a spell. If the spell IS an attack you can change the "Output" selector from "Spellcard" to "Attack", this will show some additional input fields to fill out the attack information about the spell. Switching this input will also add an attack entry to the [[D%26D_5E_by_Roll20#.2811.29_Attacks_.26_Spellcasting|Attacks & Spellcasting]]-section on the [[#Core Page|Core page]] so this spell attack can also be cast from the main page. All of these sections are linked, so changing information in one place will also change the corresponding information in the other location. To save your edits, click on the gear icon at the upper right of the entry to collapse the spell entry.<br />
<br />
You can edit any spell at any time, by hovering your mouse over the entry to make a <span style="font-family:Pictos;">y</span> icon appear on the left. Clicking on the <span style="font-family:Pictos;">y</span> will roll out the spell once more to be edited.<br />
<br />
==Settings Page==<br />
[[File:D&D5E-by-Roll20-Settings-Page.png|thumb|right|400px|The Settings tab of the sheet, accessed from the '''<span style="font-family:Pictos;">y</span>''' icon ]]<br />
The Settings page, accessed by selecting the <span style="font-family:Pictos;">y</span>(gear) icon from the four buttons near the top right of the sheet, is where you can make changes to some parts of your character sheet that aren't represented on the other pages.<br />
<br />
===Class Options===<br />
In the class options section is where you have access to some important parts of your character, that usually are managed in the background. They are placed here so that, if needed they can be modified as well.<br />
<br />
'''Hit Dice:''' This section will be set automatically depending on the class chosen on the [[#Core Page|Core page]], but can be changed here by selecting the value and choosing a new one from the drop-down menu. This option is used whenever the "Hit Dice" section is used on the Core page.<br />
<br />
'''Carrying Capacity Modifier:''' This modifier allows you to increase the weight that a character can carry before they become encumbered.<br />
<br />
'''Global Magic Attack Modifier:''' This modifier will affect all spell attacks rolled from the sheet.<br />
<br />
'''Magic Caster Level:''' By default, a character's caster level is tethered to their class level. This option allows you to set the caster level manually, so you can have it differ from the character's class level. This will automatically change the Spell Slots Total for each spell level on the [[#Spell Page|Spells page]].<br />
<br />
'''Spell Save DC Mod:''' The Spell Save DC is normally a field you can't edit from the Spell page and is set by the character's class and level. This modifier allows you to alter that value.<br />
<br />
'''Spell Icons:''' This option will allow you to choose to turn off all the Spell Icons (R, C, V, S, & M), show them all, or only display only the ritual and concentration icons.<br />
<br />
'''Halfling Luck:''' Use this checkbox if your character is a Halfling that happens to take advantage of the Halfling Luck race feat. Using this feat will automatically re-roll any 1s rolled for attacks and skills or ability checks/saves.<br />
<br />
'''Arcane Fighter/Rogue:''' These checkboxes can be used to keep track of when your Fighter or Rogue-classed character actually has access to spells.<br />
<br />
===Multiclass Options===<br />
If you are taking advantage of the D&D 5E multiclassing you can keep track of it in this section. Any levels to your character's additional classes must be changed here, and will then be reflected in the header portion of the sheet. Once you've added additional classes in this section, any time you roll Hit Dice from the Core page it will ask you which classes hit dice you wish to use.<br />
<br />
Note: Be sure to not re-include your main class in this section, or your final level calculation will be incorrect.<br />
<br />
===Custom Class Options===<br />
If you are playing a class that is not part of the D&D 5E Compendium, you can input the important class information in this section, and checking the "Use Custom Class" checkbox will replace the main class selection with your custom built class.<br />
<br />
===Spell Slot Modifiers===<br />
This section allows you to manually modify how many spell slots your character has available for each spell level from 1 to 9.<br />
<br />
===Attribute Options===<br />
'''Attribute Modifiers:''' With this section you can manually adjust the individual Attribute Scores for Strength, Dexterity, Constitution, Intelligence, Wisdom, and Charisma.<br />
<br />
'''Initiative Modifier:''' Usually, your initiative modifier is just based off of your DEX modifier, but if you happen to find a magical item that enhances these rolls this is where you will put that bonus. This modifier will be used whenever the [[#.287.29_Armor_Class.2C_Initiative.2C_.26_Speed|Initiative]]-section is rolled on the Core page.<br />
<br />
'''Initiative Style:''' This setting allows you to select whether Initiative will be rolled with Advantage, Disadvantage, or rolled normally with a single d20 (default).<br />
<br />
'''Add DEX Tiebreaker to Initiative:''' If you would like to enable a tie breaker component to Initiative, this checkbox will enable adding your dexterity Attribute Score as a decimal value to your Initiative roll. So if you have a character with a dexterity attribute score of 14, your initiative modifier will change from a 2 to a 2.14.'<br />
<br />
'''Global Armor Class Modifier:''' This setting will modify your armor class and will be taken into account regardless of the equipment the character uses.<br />
<br />
'''Armor Class Tracking:''' There are three options available: The Automatic version that's default to the sheet where it adds 10 + your DEX modifer and then takes any armor equipped into account. A Custom version which expands out a formula upon selection where you can input your own formula for armor tracking, or you can turn Off Armor Tracking entirely. When turned off, you will need to manually adjust the Armor Class field on the Core page.<br />
<br />
===Save Options===<br />
'''Save Modifiers:''' With this section you can manually adjust the individual Save modifiers for Strength, Dexterity, Constitution, Intelligence, Wisdom, and Charisma.<br />
<br />
'''Death Save Modifier:''' A normal death save is usually just a D20 against a dc of 10, but if you're lucky enough to have a bonus to death saves, this is where you will put your bonuses. This modifier will be represented any time a "Death Save" is rolled from the Core page.<br />
<br />
'''Global Saving Throw Modifier:''' If you have an affect that would modify all saving throws, this option makes it easier to adjust your Save modifiers than having to go in and change each one individually. This modifier will be used every time any save is rolled from the sheet.<br />
<br />
===Skill Options===<br />
If your class offers the ability to achieve "Expertise" in a skill, or if you are using a Bard with the "Jack of All Trades" feat, this is where you will make these adjustments. There is also a section to add flat modifiers to any of your skills if your character has an archetype ability like Remarkable Athlete or a feat that adds a flat bonus to a skill. You can add expertise to any skill by clicking the value next to it and choosing "Expertise" from the drop-down menu. If your Bard has the Jack of All Trades feat, you can check the checkbox at the bottom of this section and it will automatically give half of your character's proficiency points to any skill check that doesn't have full proficiency.<br />
<br />
'''Passive Perception Modifier:''' This option will add a bonus to a character's Passive Perception which is not something you can change directly from the Core page of the sheet.<br />
<br />
===General Options===<br />
The General Options section has some important options that deal more with how the sheet works, rather than actual character creation. Most importantly, the NPC checkbox at the top, which will change the sheet to be the NPC version which is shaped to more easily track an NPC's information.<br />
<br />
'''Roll Queries - Always/Toggle/Query/Never Roll Advantage:''' This option will change how advantage is rolled for all attacks. It defaults to always roll advantage, which means that every time an attack is rolled it will roll twice and present the outcome of both rolls. This is useful for both advantage and disadvantage, otherwise you can just choose either the left or the right to be the default roll. Toggle adds a set of buttons at the top of the sheet to manually switch your advantage options between rolls. If Query is chosen, every time a roll is made it will ask you whether or not it's advantage. If Never is chosen, then it will always roll just a single dice per attack roll.<br />
<br />
'''Whisper Rolls to GM:''' Like above, you have the option to Never/Toggle/Query/Always whisper rolls to the GM. When this option is enabled, the attack roll will only be whispered to the GM and not made public.<br />
<br />
'''Auto Damage Roll:''' By default, damage rolls will not be rolled automatically, but only when you click the attack in the chat window. This is useful because you can choose to only roll damage when an attack hits. Using this option you can make the character always roll damage with every attack.<br />
<br />
'''Core Die Roll:''' You can change the core die (by default it is 1d20) to something else entirely here.<br />
<br />
'''Proficiency Bonus:''' By default, the character's Proficiency Bonus is calculated by class level. This setting allows you choose to calculate this bonus via By Level (the default), via a Proficiency Die as described in the Dungeon Master's Guide, or a Custom calculation which rolls out a field to enter a roll formula for the bonus.<br />
<br />
'''Global Save/Skill/Attack/Damage Modifier Field:''' This series of checkboxes will add new entries to the Saving Throws, Tools Proficiencies & Custom Skills, and Attacks & Spellcasting blocks respectively to add global modifiers (like if a character is under the effects of a Bless or Guidance spell). Each entry will have a Global label in grey at the bottom of its entry and a field to enter the modifier bonus. If you include a word in brackets with the bonus formula (ex. "1d4[Bless]"), the word enclosed in the brackets will appear when you mouse over a roll to see it's formula.<br />
<br />
'''Add Character Name to Templates:''' This option allows you to turn this on or off. When it is on, the character's name is listed in the roll template when rolls are made from the sheet. If the character sheet in question is for an NPC, you will likely want to have this off so the rolls don't accidentally show your hand of what sort of monster your party is facing. This setting is off by default.<br />
<br />
'''Auto Level Calculations:''' This option allows you to turn this on or off. When it is on, adjusting the character's class level will automatically update the character's proficiency bonus, Hit Dice, and spell Slot totals (if the class is a spellcaster).<br />
<br />
'''Encumbrance:''' This option dictates how encumbrance is handled on the Equipment block of the Core page. This requires your Inventory to be set to "Compendium Compatible" to automatically calculate and track the weight of your character's backpack if you enter the weight values for any of the items in your Equipment list. When your character becomes encumbered, and depending on its severity, the words ENCUMBERED, HEAVILY ENCUMBERED, or IMMOBILE will display in red underneath the TOTAL WEIGHT value. This setting has three options: Simple Encumbrance Rules, Variant Encumbrance Rules, or not follow Encumbrance rules at all by toggling it off from this.<br />
<br />
'''Inventory:''' With this option allows you to either have your Equipment block be "Compendium Compatible" or "Simple". The Simple version of the Equipment block will give you single text field to log your inventory. The Compendium Compatible version tracks weight, quantity, and attack options in an itemized list for every equipment item you add to the block.<br />
<br />
'''Features & Traits:''' This option can set the Features & Traits block to be either a single text field or a repeated section that will be Compendium Compatible to list traits and features in an itemized list.<br />
<br />
'''Proficiencies & Languages:''' This option can set the Proficiences & Languages block to be either a single text field or a repeated section that will be Compendium Compatible to list traits and features in an itemized list.<br />
<br />
'''Ammo Tracking (API Required):''' When using the 5th Edition OGL Companion API Script in your game (Pro Subscriber feature), you can set attacks to weapons using ammunition to automatically subtract from their tally in their Resource block. So if your character is equipped with a bow, rolling its attack will automatically remove an arrow from its Resource block.<br />
<br />
===Transition Options(outdated)===<br />
{{mbox | text = This feature doesn't seem to exist on the sheet any longer, so the info in this section is outdated}}<br />
<br />
If your campaign previously used the [https://wiki.roll20.net/DnD5e_Character_Sheet#Intro Community Contributed] or [https://wiki.roll20.net/index.php?title=DnD5e_Shaped_Character_Sheet&oldid=11112#General_Information Shaped Legacy] 5th Edition Character Sheets and you are swapping over to this one, we have an automated conversion tool that will clear or merge elements left over from those two sheets. This procedure can only be done ''once'' and can not be undone. It is recommended that you make a copy of your campaign first before attempting a sheet transition.<br />
<br />
There is also a checkbox that hides this feature entirely from the sheet. If you hide this by mistake, you can gain access to it again by creating a new character journal.<br />
<br />
=The NPC Sheet=<br />
''See Also:'' '''[[D&D5E by Roll20 NPC Attributes]]'''<br />
<br />
One of the most useful parts of the D&D 5E by Roll20 Character Sheet is that it contains both a PC sheet ''AND'' an NPC sheet. An NPC doesn't normally require the depth a PC sheet needs, so the NPC sheet is a much more slimmed down character sheet that doesn't require multiple pages like its PC counterpart. You can access this version of the sheet by going to the Settings Page, by clicking the gear icon near the top right of the sheet, and then checking the NPC checkbox. This will switch the sheet to the NPC version. You can switch back at any time by unchecking the NPC option under General Options on the new page.<br />
<br />
==NPC Options==<br />
[[File:5E_OGL_Sheet_NPC_Options.png|right|thumb|250px|The NPC Options Section]]This is the area where all of the NPC's stats will be entered, it covers everything from the NPC's name, to how strong or quick or smart it is, to what languages it speaks. Most of the fields in this section are just text fields used to keep track of information about the NPC. All of the information entered in these fields will be visible in the stat block once the NPC options are hidden. <br />
<br />
<br />
Any text that appears in light grey is placeholder text. It's there to offer you an example of what the content would be for any given field. <br />
<br />
By default, no skill or ability checks will show up in the NPC's stat block. Once you've added a value to the corresponding skill or ability save, they will appear. If for some reason the NPC will have to make a check with a skill or ability it does not have any bonus in, you can enter a 0 as the modifier for that check and it will add it to the list in the stat block below.<br />
<br />
The XP of an NPC auto-calculates based on its given challenge rating.<br />
<br />
If the NPC is a spellcaster, you can check the checkbox beside '''SPELLCASTING NPC''' and this will add a spell list section that utilizes the spell list and its functionality from the PC version of the sheet.<br />
<br />
At default, you can add Traits and Actions in their respective places after the Challenge Rating and XP area of the Stat Block. For Reactions and Legendary Actions, you need to enable them from the NPC Options section. For Reactions, check off the '''HAS REACTIONS''' checkbox. This will add a new sections to the Stat Block for you to add Reactions to. If an NPC is a monster with Legendary Actions then you must enter the number of actions that monster has access to each turn in the '''LEGENDARY ACTIONS:''' field. Once you add a number here, an additional section will appear in the stat block below, where you can add the specific legendary actions that the monster is able to do.<br />
<br />
The NPC sheet supports Compendium drag & drop. If you want to add a new monster to your game just drag the monster from the <span style="font-family:Pictos;">i</span> [[Compendium]]-tab of the [[Sidebar]] and drop it to anywhere on the Tabletop. This will automatically create a new journal entry named the same as the Compendium entry and will copy all of the information on that compendium page directly into the new sheet. If you have purchased any of the Compendium expansions that expands on the available NPCs like the Monster Manual or Volo's Guide to Monster, a token of that NPC will be added to the Tabletop that will have its stats automatically set and linked to the new journal entry.<br />
<br />
{{mbox | text = '''Note:''' If you already have a journal entry in your {{journal}}-tab with the exact same name as the <span style="font-family:Pictos;">i</span> [[Compendium]] entry, the drag and drop will not work as this automation will stop to prevent overwriting existing content the user has already created. If a drag and drop of an NPC Compendium page does not create a journal entry, run a search for that NPC's name in your Journal to see if an entry already exists. If you do not want to delete the older entry, renaming it will allow the drag and drop to work as expected.}}<br />
<br />
===General Options===<br />
Within the NPC Options section, directly below the Legendary Actions field, is the General Options that are featured on the PC Sheet: NPC checkbox, WHISPER ROLLS TO GM, and the AUTO DAMAGE ROLL options. <br />
<br />
*NPC checkbox<br />
*WHISPER ROLLS TO GM<br />
*AUTO DAMAGE ROLL<br />
*NPC NAME IN ROLLS<br />
*ADD DEX TO TIEBREAKER TO INITIATIVE<br />
<br />
Unchecking the NPC checkbox from here will revert the sheet back to the PC Sheet.<br />
<br />
===Hiding NPC Options===<br />
Once all of the desired information has been entered, you can click the <span style="font-family:Pictos;">y</span>(gear) icon at the top right to hide this section. This leaves behind just the NPC's stat block where you can make all of your rolls from. You can re-open this section to edit the information at any time by clicking on the <span style="font-family:Pictos;">y</span> icon again. It's in the same location regardless if you're looking at NPC Options or the NPC stat block.<br />
<br />
==The NPC Stat Block==<br />
[[File:5E OGL Sheet NPC v2.png|right|thumb|250px|An NPC stat block for a griffon]]Following NPC Options is the NPC Stat Block that is built off of what you input in the NPC Options section. This area may look very similar to a stat block you may find in a monster bestiary or published adventure.<br />
<br />
<br />
Any section of the stat block that has a corresponding roll will have click-able text. For example, if the NPC has to make a CON check, you can click the CON attribute to roll a CON check with all of the required modifiers automatically included. If you added a value to one of the skill modifier fields then that skill will show up in the NPC's "Saving Throws" list where you can click it to make a saving throw roll using that skill's modifier.<br />
<br />
The first section of the Stat Block mirrors all the information you added in the NPC Options section. This content is meant exclusively for rolling and can not be edited directly. You will need to change them from the NPC Options section.<br />
<br />
===Traits===<br />
Traits are pieces of information about an NPC that isn't covered by the NPC options section. These are entered directly onto the NPC's stat block. If you click the "<span style="font-family:Pictos;">&</span>" button that appears right below the "Senses/Languages/Challenge Rating" section it will add a blank entry where you can add a single trait for that NPC. Each Trait Entry features a bold title field which is then followed by a larger text box for the description of the trait. You can add any number of Traits for any NPC.<br />
<br />
===Actions===<br />
NPC actions can be used for any number of things. Each entry initially offers an Action Name field as well as a large text field for the Action description. The checkbox for ATTACK, once checked, adds more structured data fields needed for an attack roll (Type, Range/Reach, To Hit bonus, Target, Damage Roll, and Damage Type). To add a new entry you will select the <span style="font-family:Pictos;">&</span> button that appears below the Actions section. Once all of this is complete you can click the <span style="font-family:Pictos;">y</span>(gear) icon at the top of this entry to hide the input fields, leaving just the action text. You can show this information, or roll the attack, in the chat box by clicking the text for the action. If you need to make further modifications to any action you can hover over the row you wish to edit, then click on the <span style="font-family:Pictos;">y</span>(gear) icon again. This will show all of the action information input fields again. You can add any number of Actions for any NPC.<br />
<br />
===Bonus Actions===<br />
NPC bonus actions are typically not listed on the sheet, and are usually referenced in the Traits section. However, if a player wishes to use this section, it is available if the 'Bonus Action' checkbox is selected. The fields work the same as the Actions section.<br />
<br />
===Reactions===<br />
Once enabled from the NPC Options section, a new heading labeled "Reactions" and its relevant section is added to the stat block that allows you to add Reactions. These entries operate just like Traits.<br />
<br />
===Spells===<br />
Once enabled from the NPC Options section, a new heading labeled "Spells" and its relevant section is added to the stat block that allows you to add Spells. These entries will operate identically to how Spells are added and handled on the PC Sheet with the one noted exception that there is only a single column of spell entries. You can drag spells from the Compendium to add spell entries just like you would with the PC's Spell sheet. Any and all spells added to the character sheet are shared between the NPC and the PC versions.<br />
<br />
===Legendary Actions===<br />
If a number value is added to the LEGENDARY ACTIONS field in the NPC Options section, the Legendary Actions heading and section is added at the very bottom of the stat block and lists some verbiage on how many actions are available to be used on a given turn. This number is dictated by what you entered in the NPC Options. These entries operate the same way as Traits.<br />
<br />
==Rolling for Initiative for NPCs==<br />
There are two ways to roll for Initiative on the NPC sheet. You can click on the NPC's Name to roll for Initiative or you can roll from the die icon labeled INIT that is listed to the right of the Armor Class and Hit Points section of the NPC sheet, towards the top. If you have the Turn Tracker tool open, having the NPC token selected while rolling Initiative will automatically add the NPC and its initiative roll to the tracker. Creatures on the GM layer that are added to the tracker in this fashion will have their entries hidden from the players.<br />
<br />
<br />
You can also create a global Macro that will pop up as a Token Action button in the upper left hand corner of the tabletop every time a token is selected. This will allow you to roll without looking at the NPC sheet at all. The macro formula should look just like this:<br />
<br />
<code>%{selected|npc_init}</code><br />
<br />
=Advanced Use=<br />
<br />
===Custom Skills and Stats===<br />
You can set up any number of custom skills or rolls from the [[#Tool Proficiencies|Tool Proficiencies]] section just underneath the skill section on the Core tab. [[#Class & Other Resources|The Resources]] section is also useful for tracking custom stats to your campaign, game setting, or home-brew rules. There are also various options available from the Settings page to modify attributes, skills, saves, spells, and more.<br />
<br />
===Target Roll Buttons===<br />
A useful way for GMs and Players to reference their abilities is by dynamically setting up a handful of macros that can be used on a token linked to a character, rather than having to roll directly from the sheet. To do this, you'll set up a global macro from the {{Collections}}-tab. You can also write these directly in the {{Text Chat}}.<br />
<br />
In the examples, the <code>selected</code> part can be replaced with <code>target</code>, a character's name, or it's character ID.<br />
<br />
Here are some examples:<br />
<br />
'''PC'''<br />
* Attributes: <code>%{selected|strength}</code>, <code>%{selected|strength_save}</code> | Will roll the Strength Check and Strength Save for the selected [[token]](if the [[Link Token|token is linked to a sheet]])<br />
* <code>%{selected|acrobatics}</code><br />
* <code>%{selected|initiative}</code><br />
* <code>%{selected|death_save}</code><br />
* <code>%{selected|hit_dice}</code><br />
<br />
'''NPC'''<br />
* <code>%{selected|npc_init}</code><br />
* <code>%{selected|npc_str}</code><br />
* <code>%{selected|npc_stealth}</code><br />
* <code>%{selected|npc_hpformula}</code><br />
====Dynamic References to Repeating Sections====<br />
The example we'll be using today is setting up the 1st NPC action:<br />
<code>%{selected|repeating_npcaction_$0_npc_action}</code><br />
Now whenever you use this macro it will roll the first NPC action of whichever NPC token you have selected. You can set up a roll for each action by incrementing the 0 by 1 for each action you wish to add (I.E. <code>$1</code>, <code>$2</code>, <code>$3</code>). Here is a list of important repeating section rolls and their formulas:<br />
<br />
* Player Attack/Spell Attack <code>%{selected|repeating_attack_$0_attack}</code><br />
* Player Attack/Spell Damage <code>%{selected|repeating_attack_$0_attack_dmg}</code><br />
* Player Attack/Spell Critical Damage <code>%{selected|repeating_attack_$0_attack_crit}</code><br />
* Player Global DMG mod <code>%{selected|repeating_damagemod_$0_global_save}</code><br />
** Attr names: <code>global_damage_name</code>, <code>global_damage_damage</code>, <code>global_damage_critical_damage</code>, <code>global_damage_type</code><br />
* Proficiencies <code>%{selected|repeating_proficiencies_$0_output}</code><br />
* Tool/Custom Skill <code>%{selected|repeating_tool_$0_tool}</code><br />
* Traits/Feats: <code>%{selected|repeating_traits_$0_output}</code><br />
<br />
* Spellbook Cantrip <code>%{selected|repeating_spell-cantrip_$0_spell}</code><br />
* Spellbook Level 1 <code>%{selected|repeating_spell-1_$0_spell}</code><br />
* Spellbook Level 2 <code>%{selected|repeating_spell-2_$0_spell}</code><br />
* Spellbook Level 3 <code>%{selected|repeating_spell-3_$0_spell}</code><br />
* Spellbook Level 4 <code>%{selected|repeating_spell-4_$0_spell}</code><br />
* Spellbook Level 5 <code>%{selected|repeating_spell-5_$0_spell}</code><br />
* Spellbook Level 6 <code>%{selected|repeating_spell-6_$0_spell}</code><br />
* Spellbook Level 7 <code>%{selected|repeating_spell-7_$0_spell}</code><br />
* Spellbook Level 8 <code>%{selected|repeating_spell-8_$0_spell}</code><br />
* Spellbook Level 9 <code>%{selected|repeating_spell-9_$0_spell}</code><br />
<br />
'''NPC'''<br />
* NPC Traits/Abilities<code>%{selected|repeating_npctraits_$0_npc_roll_output}</code><br />
* NPC Actions/Attacks<code>%{selected|repeating_npcaction_$0_npc_action}</code><br />
* NPC Attack Damage<code>%{selected|repeating_npcaction_$0_npc_dmg}</code><br />
* NPC Attack Critical Damage<code>%{selected|repeating_npcaction_$0_npc_crit}</code><br />
* NPC Bonus Actions<code>%{selected|repeating_npcbonusaction_$0_npc_action}</code><br />
* NPC Legendary Actions<code>%{selected|repeating_npcaction-l_$0_npc_action}</code><br />
* NPC Mythic Actions<code>%{selected|repeating_npcaction-m_$0_npc_action}</code><br />
* NPC Spells<code>%{selected|repeating_spell-npc_$0_spell}</code><br />
<br />
===Directly Referencing Attributes===<br />
You can discover the name of most of the attributes in the sheet by hovering over them. After a couple of seconds a title will pop up and tell you how to referencing them. You can call attributes in an Ability Rolls by using <code>@{attributename}</code>. If you want to directly reference it in a roll that isn't saved on the sheet, you need to specify the character's name, or use either the <code>selected</code> or <code>target</code> key works.<br />
<br />
'''Examples:'''<br />
* <code>/em attempts to grapple and gets [[1d20+@{strength_mod}]]</code> custom [[Journal#Attributes_.26_Abilities_Tab|Ability call]], saved in the "attributes and abilities" tab of the character sheet.<br />
* <code>/r 1d20+@{Alice|strength_mod}+@{Alice|pb}</code> macro that calls a specific character<br />
* <code>/em have @{selected|hp} out of @{selected|hp|max} left.</code> macro that uses stats from a token(token must be selected before rolling)<br />
* <code>The Enemy's AC is @{target|npc_ac}</code> macro prompt the user to select a target token on the map, and uses it's stats.<br />
<br><br />
<br />
See [[Macros#Attribute_Macros]] for further general details/examples on the syntax.<br />
====PC====<br />
Here are a list of some of the more important stats:<br /><br />
<br />
'''Attributes/Saves:'''<br />
<br />
* Str: <code>strength, strength_mod, strength_save_bonus</code><br /><br />
* Dex: <code>dexterity, dexterity_mod, dexterity_save_bonus</code><br /><br />
* Con: <code>constitution, constitution_mod, constitution_save_bonus</code><br /><br />
* Int: <code>intelligence, intelligence_mod, intelligence_save_bonus</code><br /><br />
* Wis: <code>wisdom, wisdom_mod, wisdom_save_bonus</code><br /><br />
* Cha: <code>charisma, charisma_mod, charisma_save_bonus</code><br />
<br><br />
'''Skills:'''<br />
<br />
<code>athletics_bonus<br /><br />
acrobatics_bonus<br /><br />
animal_handling_bonus<br /><br />
arcana_bonus<br /><br />
deception_bonus<br /><br />
history_bonus<br /><br />
insight_bonus<br /><br />
intimidation_bonus<br /><br />
investigation_bonus<br /><br />
medicine_bonus<br /><br />
nature_bonus<br /><br />
perception_bonus, passive_wisdom<br /><br />
performance_bonus<br /><br />
persuasion_bonus<br /><br />
religion_bonus<br /><br />
sleight_of_hand_bonus<br /><br />
stealth_bonus<br /><br />
survival_bonus<br /><br />
</code><br />
<br />
'''AC, Proficiency, HD etc'''<br />
<br />
<code>pb</code>(Proficiency Bonus)<br><br />
<code>inspiration</code><br><br />
<code>ac<br /><br />
initiative_bonus<br /><br />
speed<br /><br />
hp, hp|max, hp_temp<br /><br />
hit_dice, hit_dice|max, hitdietype<br /><br />
weighttotal<br /><br />
</code><br />
<br />
'''Spells'''<br />
<br />
<code>spell_save_dc, spell_attack_bonus<br /><br />
lvl1_slots_total, lvl1_slots_expended<br /><br />
lvl2_slots_total, lvl2_slots_expended<br /><br />
lvl3_slots_total, lvl3_slots_expended<br /><br />
lvl4_slots_total, lvl4_slots_expended<br /><br />
lvl5_slots_total, lvl5_slots_expended<br /><br />
lvl6_slots_total, lvl6_slots_expended<br /><br />
lvl7_slots_total, lvl7_slots_expended<br /><br />
lvl8_slots_total, lvl8_slots_expended<br /><br />
lvl9_slots_total, lvl9_slots_expended<br /><br />
</code><br />
<br />
Spells, repeating sections:<br><br />
<code>repeating_spell-cantrip<br><br />
repeating_spell-1<br><br />
repeating_spell-2<br><br />
repeating_spell-3<br><br />
repeating_spell-4<br><br />
repeating_spell-5<br><br />
repeating_spell-6<br><br />
repeating_spell-7<br><br />
repeating_spell-8<br><br />
repeating_spell-9</code><br> <br />
<br />
Cantrip stats(most should also work for lvl.1-lvl.9):<br><br><br />
Full statname is spell level + (rowID or row number) + attribute name, e.g. <code>repeating_spell-1_$0_spellname</code> is the spell name of your first Lvl 1 spell, <code>repeating_spell-4_$1_spelldescription</code> is the description of your second lvl.4 spell.<br />
<br />
<code>spellname<br><br />
spellrange, spellcastingtime, spelltarget, spellduration<br><br />
spellschool<br><br />
spellritual<br><br />
spellconcentration<br><br />
spellcomp_v, spellcomp_s, spellcomp_m<br><br />
spellcomp_materials<br><br />
spell_ability<br><br />
spelloutput<br><br />
spellattack<br><br />
spelldamage, spelldamagetype, spelldamage2, spelldamagetype2<br><br />
spellhealing<br><br />
spelldmgmod, spell_damage_progression<br><br />
spellsave, spellsavesuccess<br><br />
spelldescription<br><br />
spellclass, spellsource</code><br />
<br />
'''Items'''<br><br />
<code>cp sp ep gp pp</code><br><br />
(copper pieces, silver, gold, electrum, platinum)<br />
<br />
<code>repeating_inventory_$#_itemcount<br><br />
repeating_inventory_$#_itemname<br><br />
repeating_inventory_$#_itemweight<br><br />
repeating_inventory_$#_equipped<br><br />
repeating_inventory_$#_useasresource<br><br />
repeating_inventory_$#_hasattack<br><br />
repeating_inventory_$#_itemproperties<br><br />
repeating_inventory_$#_itemmodifiers<br><br />
repeating_inventory_$#_itemcontent</code><br><br />
<br />
* <code>equipped</code>, <code>useasresource</code>, <code>hasattack</code> are checkboxes, with value 1 if checked.<br />
* <code>itemmodifiers</code> is for of item changes any stats, like <code>AC +2</code> adding +2 to AC when equpped.<br />
* <code>itemcontent</code> is the item description<br />
<br><br />
'''The class_resource and the other_resource'''<br><br />
<br />
<code>class_resource</code> and <code>other_resource</code> are static resources. That is to say, you need to keep in mind that they are NOT a part of the repeating section, even though it definitely looks that way on the character sheet.<br><br />
<br />
You use these to access them<br />
<br />
<code>class_resource</code><br><br />
<code>class_resource_max</code><br><br />
<code>class_resource_name</code><br><br />
<code>other_resource</code><br><br />
<code>other_resource_max</code><br><br />
<code>other_resource_name</code><br><br />
<br />
'''The repeating resources'''<br><br />
<br />
Any resources that appear beneath the "class resource" and the "other resource" are a part of the "repeating resources" section. This section is known for being confusing for beginners, so it deserves a bit of clarification.<br />
<br />
First, keep in mind that this is one section (not two sections, as people often think), and that "repeating_resource" is its section prefix.<br />
<br />
Second, keep in mind that you need to skip past the row with the "class resource" when you're figuring out the address of the row that you want to refer to. So basically, if you want to refer to the row that is directly below the row with the "class_resource", then you would add "_$0" (to form "repeating_resource_$0"). And then the next row after that is "_$1", and so on.<br />
<br />
Third, keep in mind that if you add "_resource_left" (to form "repeating_resource_$0_resource_left"), then you are specifying that you are talking about the CURRENT VALUE of the leftmost resource in that row. And if you add "_resource_left_max", then you are specifying that you are talking about the MAX VALUE of the leftmost resource in that row.<br />
<br />
Here is a complete list of all the fields that you can access in the "repeating_resource" section. Just replace the "#" character with which row you want to access.<br />
<br />
<code>repeating_resource_$#_resource_left</code><br><br />
<code>repeating_resource_$#_resource_left_max</code><br><br />
<code>repeating_resource_$#_resource_left_name</code><br><br />
<code>repeating_resource_$#_resource_right</code><br><br />
<code>repeating_resource_$#_resource_right_max</code><br><br />
<code>repeating_resource_$#_resource_right_name</code><br><br><br />
<br />
<br />
'''Features/Class Traits'''<br />
<br />
<code>repeating_traits_$0_output<br><br />
repeating_traits_$#_name<br><br />
repeating_traits_$#_source<br><br />
repeating_traits_$#_source_type<br><br />
repeating_traits_$#_description<br><br />
</code><br />
<br />
'''Other/Settings:'''<br />
<br />
<br><br />
<code><nowiki>wtype</nowiki></code> (whisper type, can have one of these values:)<br />
* <code><nowiki></nowiki></code> (empty for never whisper)<br />
* <code><nowiki>@{whispertoggle}</nowiki></code> (show the buttons on sheet that can toggle between options)<br />
* <code><nowiki>?{Whisper?|Public Roll,|Whisper Roll,/w gm }</nowiki></code><br />
* <code><nowiki>/w gm</nowiki></code> (always whisper)<br />
<br />
<br />
'''Global modifiers'''<br />
<br />
* <code>repeating_savemod_$0_global_save_roll</code><br />
* <code>repeating_skillmod_$0_global_skill_roll</code><br />
* <code>repeating_tohitmod_$0_global_attack_roll</code><br />
* <code>repeating_damagemod_$0_global_damage_damage</code><br />
<br />
====NPC====<br />
Some stats are the same as for PCs<br />
<br />
<code>npc_name<br><br />
npc_ac<br><br />
hp, hp|max<br><br />
npc_speed<br><br />
npc_challenge<br><br />
npc_xp</code><br />
<br />
Attributes: <code>strength_base, strength_mod</code> (same as PCs)<br />
Saves:<br />
<br />
<code>npc_str_save_base</code>,<code>npc_dex_save_base</code>, <code>npc_con_save_base</code>,<code>npc_int_save_base</code>,<code>npc_wis_save_base</code><code>npc_cha_save_base</code><br />
Skill bonus:<code>npc_acrobatics_base</code>, <code>npc_animal_handling_base</code> etc.<br />
<br />
Damage/Conditions stuff:<br />
<br />
<code>npc_vulnerabilities<br><br />
npc_resistances<br><br />
npc_immunities<br><br />
npc_condition_immunities</code><br />
<br />
Spells:<br />
<br />
<code>npcspellcastingflag</code> (set to "1" if caster, empty otherwise) <br />
<code>spellcasting_ability</code><br />
<code>globalmagicmod </code> (global magic attack modifier)<br />
<code>caster_level</code><br />
<code>spell_dc_mod</code> (spell save DC mod)<br />
<br />
Spells are identical to PC section<br />
<br />
Other:<br />
whisper is same as PCs<br />
<br />
<code>npc_name_flag</code> (show/hide npc name in rolls, value is either <code><nowiki>{{name=@{npc_name}}}</nowiki></code> or <code>0</code>)<br />
<br />
<br />
<sup>Note: anything with the Suffix of <code>|max</code> requires some form of Prefix, such as <code>selected|</code> making the call for such a thing look something along the lines of <code>@{selected|hp|max}</code>. The <code>|max</code> Suffix specifically calls the box on the right of the selected Attribute's Line, for example, you could fill in the Weight Total's 2nd Box with <code>@{strength}*15</code> & whenever you call <code>@{selected|weighttotal|max}</code> it will tell you your 5e standard Maximum Carry Capacity for your current Strength Score.<br />
<br />
===Custom AC Items===<br />
You can add pieces to your inventory and manually give them AC or magic bonuses that will figure into their calculations automatically. Inside the item options is a section for "MODS:". Add <code>Ac +1</code> to add an armor class bonus.<br />
<br />
===Roll Templates===<br />
''Main Article:'' '''[[D&D 5e by Roll20 Roll Templates]]'''<br />
<br />
The '''D&D5E by Roll20''' Character Sheet also includes a series of [[Roll Templates]] that you can use to dress up your own custom macros. Roll Templates provide additional layout and styling options for the display of roll results.<br />
<br />
{{ex}}<br />
[[File:5e-rolltemplate-ex1-2021.png|200px|right|none]]<br />
Rolls stealth for selected npc token, using it's stealth proficiency.<br />
<code><nowiki>/w gm &{template:npcatk} {{attack=1}} {{name=Shadow}} {{rname=Shadow Stealth}} {{rnamec=Hide}} {{r1=[[@{selected|d20}+@{selected|npc_stealth} + 6]]}} {{always=1}} {{r2=[[@{selected|d20}+@{selected|npc_stealth} + 6]]}} {{description=While in dim light or darkness, the shadow can take the Hide action as a bonus action. Its stealth bonus is **also** improved to +6 }}</nowiki></code><br />
<br />
===Magic Missile Spell===<br />
{| role="presentation" class="wikitable mw-collapsible mw-collapsed" style="float:right; margin-left: 10px;margin-right: 60px;"<br />
| Image of the Spell's settings<br />
|-<br />
| [[File:Magic-Missile-5E-2020.png|right|frame|The Magic Missile Spell]]<br />
|}<br />
<br />
RAW, Magic Missile is rolled once, and the single roll is then used for each hit. So by default the spell rolls <code>1d4+1</code>. (See [[Talk:D&D 5E by Roll20#Old Magic Missile Discussion]] for more info.)<br />
<br />
You can modify the spell to instead roll 3d4+3 at first level, and then in the ''HIGHER LVL CAST DAMAGE'' section, set it to <code>1d4+1</code>.<br />
<br />
To automatically use higher-level spell slots with Magic Missile, you have to write a 0 into the ''HIGHER LVL CAST DAMAGE'' section of the spell and select any die. It will show the box for selecting higher-level spell slots when launching Magic Missile, but since it multiplies the higher-level damage cast by 0, the added roll doesn't show up in the chat, making it roll a single die for every missile while using any level spell slot.<br />
<br />
=API=<br />
{{pro only|section}}<br />
[[API:Introduction|API Scripts]] allow for greater customization and functionality to how Roll20 operates beyond what it can do at default. This section will list some info on using various APIs that interact with the character sheet.<br />
<br />
Example of APIs from the One-Click Install menu, that designed to be used with the '''D&D 5E by Roll20''' sheet:<br />
* '''5E BattleMaster'''<br />
* '''5E Resting in Style'''<br />
* '''CashMaster'''<br />
* '''Concentration'''<br />
* '''[[Script:It's a Trap|It's a Trap! -- D&D 5E Generic]] (should detect automatically what sheet is used)<br />
** {{repo|Roll20/roll20-api-scripts/tree/master/ItsATrap_theme_5E_Generic#readme readme}}<br />
* '''ShortRest'''<br />
* '''SpellMaster'''<br />
* '''WildShape'''<br />
<br />
A good number of the more general APIs have built in settings for configuring them for usage with the 5E sheet, such as '''GroupInitiative''', '''GroupCheck''', '''Experience Tracker''', '''[[PowerCards]]''', '''[[ScriptCards]]''' (an improved version of PowerCards)<br />
<br />
* '''[[GroupCheck]]:''' <code>!group-check-config --import 5E-OGL</code> will configure the API for use with this sheet<br />
* '''[[GroupInit|GroupInitiative]]:''' before use, API need to be configured for the sheet, either through the menu preset, or using the command: <code>!group-init --add-group --Bare </code><br />
* '''CombatMaster:''' is by default configured with conditions for D&D 5E<br />
* '''[[ChatSetAttr]]:''' API that can create, edit, & delete stats on sheets. Example: [[Script:ChatSetAttr#Add_new_thing_to_Repeating_Section|Adding a new magic item to a sheet]], with one chat command <br />
* '''[[Script:Ammo]]''' can be used for updating ammo & spellslots when used<br />
<br />
==Utilizing the ''5th Edition OGL by Roll20 Companion'' API Script==<br />
'''{{repo|Roll20/roll20-api-scripts/tree/master/5th%20Edition%20OGL%20by%20Roll20%20Companion 5th Edition OGL Companion}}'''is an official companion script for the "D&D 5E by Roll20" character sheet. The Companion currently supports Ammo Tracking, Automatic NPC Tokens, Automatic Death Save Tracking, and Automatic Spell Slot Tracking. <br />
<br />
{{mbox | text = Installing & creating [[API]] Scripts is a {{Pro}} feature. In order to be able to access these advanced scripts, the [[GM]] of the campaign must be a [[Pro]] subscriber and enable it for their campaign.}}<br />
<br />
<br />
'''''How to Add the API Script to your Game'''''<br />
<br />
If you have a PRO account, you can install the API script by going to your game's Campaign Page and clicking on the '''Settings''' button, and then choosing '''API Scripts'''. This brings you to the API Scripts page for your current game. The Companion Script is part of the One-Click Community API Installation options. Under the Script Library tab, there is a drop down menu that lists all the available community created scripts. Scroll down till you find the '''System Toolbox''' category and select the "5th Edition OGL by Roll20 Companion" script. The version number, the script's author, and a brief description of what the script does will appear right below the drop down menu once it is selected. Below that, click on the blue "Add Script" button to add the script to your game.<br />
<br />
<br />
'''''List of API commands for the 5th Edition OGL Companion API Script'''''<br />
* <code>!5ehelp</code> - Gives a list of the script's API commands in the chat tab.<br />
* <code>!5estatus</code> - Lists the current status of the script's features in the chat tab.<br />
* <code>!ammotracking on/off/quiet</code> - Automatically expends linked resource when attack is made<br />
* <code>!autonpctoken on/off</code> - Automatically generates a NPC token on the GM's screen based on the default token when an NPC's health calculation is rolled<br />
* <code>!deathsavetracking on/off/quiet</code> - Automatically ticks off successes and failures when death saves are rolled, clearing on death, stabilization, or hp recovery<br />
* <code>!longrest <character name></code> - This will add Hit Dice recover and if spelltracking is on, this command will reset all of the character's spell slots to unspent.<br />
* <code>!npchp <character name></code> - Rolls NPC hit point totals using their formula and updates the token bar. If no character name is provided it will roll the selected tokens.<br />
* <code>!spelltracking on/off/quiet</code> - Automatically expends spell charges as cast, factoring in higher level casting, and spells marked as Rituals will not spend a spell slot.<br />
<br />
<br />
Options:<br />
* ''on'' - Toggles the functionality on (default)<br />
* ''off'' - Disables the functionality<br />
* ''quiet'' - Maintains functionality while preventing results from being output to the chat.<br />
<br />
<br />
===Automatic Ammunition Tracking===<br />
''Main Article:'' '''[[D&D 5E by Roll20: How to setup Ammunition and Resource tracker]]'''<br />
<br />
Automatic Ammunition Track is a feature that requires the above Companion API Script. Once installed, follow these instructions to enable automatic ammunition tracking in your game:<br />
<br />
This example sets up a Longbow with a quiver of Arrows to track.<br />
# On the Settings (Gear Icon) tab of a character sheet, under GENERAL OPTIONS, make sure that the INVENTORY option is set to "Compendium Compatible" and not "Simple".<br />
# While still under GENERAL OPTIONS, set the AMMO TRACKING feature to ON.<br />
# Create manually or drag a missile weapon (ex. Longbow) from the Compendium to your sheet.<br />
# Create manually or drag a missile type (Arrows) from the compendium to your sheet<br />
# Expand the missile type (Arrows) by clicking on the "I" information icon that appears when hovering the mouse over the item.<br />
# Select the USE AS RESOURCE checkbox. (ammunition items dragged from the Compendium will have this option automatically checked off)<br />
# On the CORE tab, expand the missile weapon (Long Bow) in the ATTACKS & SPELLCASTING section by clicking on the gear icon that appears when hovering over the attack.<br />
# In the AMMUNITION section put the exact name of the ammunition resource (Arrows). If you want to spend more than one piece of ammunition per shot you want to add the number of pieces after the name of the ammunition resource and a comma. (ex. ''Arrows,2'' )<br />
<br />
<br />
Now, any time the missile weapon (Longbow) is rolled, a piece of ammunition will automatically be spent and the chat will make note. Additionally after the first time the missile weapon is used the AMMUNITION section will update with the ID of the resource repeating section, this is normal and expected.<br />
<br />
<br />
===Automatic Spell Slot Tracking===<br />
<br />
Automatic Spell Slot Tracking is a feature that requires the above Companion API Script. Once installed, follow these instructions to enable automatic spell slot tracking in your game:<br />
* In the chat input area of the Sidebar, type ''!5estatus'' and press Enter, to check if spelltracking is set to 'on'.<br />
* If not, type ''!spelltracking on'' and press Enter to activate this feature.<br />
* Alternatively, you may type ''!spelltracking quiet'' and press Enter to activate this feature, while preventing spelltracking messages from being displayed in the chat.<br />
<br />
<br />
<br />
Once the Spell Slot Tracking has been activated, each time a spell is cast:<br />
# The number of cast spells of the appropriate level is updated in the Spell tab of the character sheet (see [[5th Edition OGL by Roll20|Spell Levels & Spells Per Day]]).<br />
# A message is output in the chat, displaying the spell level, the number of available spell slots and the number of used spell slots for this level.<br />
# Spell slots decrement as spells are cast. <br />
# Spells that are marked as a Ritual do not affect the tally of spell slots when cast.<br />
<br />
<br />
At any time, you can manually adjust this count directly in the Spell Page of the character sheet.<br />
<br />
=Updates=<br />
* {{hc|articles/360037772613-Change-Log Roll20 Changelog}} - Full Changelog of Roll20, updates for 5E sheet are included<br />
* {{fpl|10096810/ D&D 5th Edition by Roll20 (Q2Y2021)}} often has mentions of latest updates<br />
* Major Sheet Updates:<br />
** Feats can now be selected in Charactermancer {{fpl|8891809 June 2020}}<br />
** Game [[creator]] can select which [[compendiums]] are or aren't accessible in a game. [https://app.roll20.net/forum/post/8738570/release-note-for-may-26-2020 May 26 2020]<br />
<br />
=Known Issues=<br />
The sheet has a number of known bugs and issues, some which are mentioned in the sheet's latest forum thread.<br />
<br />
'''Charactermancer/Character Creation'''<br />
* '''Charactermancer & Compendium drag-n-drop doesn't work when sheet is in a separate window.''' This is [[Character_Sheets#Character_Sheet_in_a_separate_window|an inherit limitation to how character sheets work]] at the moment. <br />
* '''Multiclassing & spell selection''' - There are troubles when multiclassing spellcasters and getting to select spells from the right lists.<br />
* '''Duplicate races/classes from Essential Kit appear in selection''' You need to uncheck EK from your compendium for it to no longer appear in selections.<br />
<br />
<br />
'''General:'''<br />
* '''Warlock spell slots''' - The Warlock's spell slots don't work too well with the sheet, and most people use some manual adjustments for how they work. The number of spell slots also appears wrong in the Charactermancer.<br />
* '''NPC stat <code>desc</code> changed into <code>description</code>''' This was a recent update that broke some macros for people, resulting in error messages along: "can't find ''desc'' attribute" {{fpl|8297517/ release notes march 2020}}<br />
<br />
=Sheet Guides=<br />
* [[5E Macros]]<br />
* {{blog|638339117446578176/tome-of-tips-dungeons-dragons-5th-edition-ogl Tome Of Tips: The D&D 5E character sheet}}<br />
* {{yt.be|9BGGr97qJdY|Learning Roll20: EP01 Character Sheets (D&D 5E)}} 50min, by Roll20 (2020)<br />
<br />
=Related Pages=<br />
* D&D 5E by Roll20 sheet<br />
** [[D&D5E by Roll20 NPC Attributes]]<br />
** [[D&D 5e by Roll20 Roll Templates]]<br />
** [[D&D 5E by Roll20: How to setup Ammunition and Resource tracker]]<br />
* [[5E]] - general D&D 5E info for Roll20. Lists also the alterantive character sheets for 5E<br />
* [[D&D]] - Roll20 stuff on the various editions.<br />
* {{Compendium}}<br />
** [[Compendium Sharing]]<br />
* [[Character Vault]]<br />
<br />
=See Also=<br />
* {{repo|Roll20/roll20-character-sheets/tree/master/DD5thEditionLegacy Sheet sourcecode}} - (Public version of sheet code is 1½+ years behind from what is actually used)<br />
* {{hc|articles/360037772613-Change-Log Roll20 Changelog}} - Full Changelog of Roll20, updates for 5E sheet are included<br />
<br /><br />
<br /><br />
[[Category:Character Sheet Documentation]]<br />
[[Category:Official Sheet]]<br />
[[Category:DnD5E]]<br />
[[Category:Featured articles]]</div>5004103https://wiki.roll20.net/D%26D_5E_by_Roll20D&D 5E by Roll202021-10-11T12:44:10Z<p>5004103: /* API */</p>
<hr />
<div>{{revdate}}{{HCbox|{{hc|360037773573-5th-Edition-OGL-by-Roll20 D&D 5E by Roll20}} }}<br />
[[File:5E OGL Sheet Core v2.6.png|500px|thumb|right|The '''D&D 5E by Roll20''' Character Sheet]]<br />
<br />
This is the community-driven documentation for the '''[[5E|D&D 5E]] by Roll20''' character sheet. Previously the sheet was known as the '''"5th Edition OGL Sheet"''' or just the '''"OGL Sheet"'''.<br />
<br />
=The Basics=<br />
This page is a ''[[Community Wiki]]'' guide to the Official D&D 5th Edition character sheet, which is updated with info tricks that might not be covered by the {{hc|articles/360037773573-5th-Edition-OGL-by-Roll20 official sheet documentation}}.<br />
<br />
<br />
To find out about the latest updates, issues and talk about the sheet, check the {{fpl|10096810/ D&D 5th Edition by Roll20 (Q2Y2021)}}-thread on the {{forum|category/277980 forums}}.<br />
<br />
<br />
[[Bug|Bug reports]] for the sheet is best reported in the same thread. If you find bugs in the 5E Compendium or 5E marketplace content, {{bug}}.<br />
<br />
<br />
__TOC__<br />
<br />
==Adding the Character Sheet to a Game==<br />
[[File:D&D5E-Roll20-sheet-selection.png|300px|thumb|right|The Sheet Selection Menu]]An official or community contributed character sheet [[Add_character_sheet#Adding_a_Character_Sheet_to_your_Campaign|can be added to any game when you first create it]]. On the Game Creation screen, underneath the large blue '''“I’m Ready, Create Game!”''' button, is the '''“Optional: Choose a Character Sheet”''' section. Located here is a drop down menu that lists all the character sheets built either by Roll20 officially or created by the community. These sheets are sorted under their respective RPG Systems in alphanumerical order. Once selected, a preview of the character sheet will load upon the creation page for you to review as well as showcase relevant information about the sheet, such as the sheet’s creator and its key features.<br />
<br />
<br />
The '''D&D 5E by Roll20''' Sheet can be found under either: '''Sheets by Roll20''' → D&D 5E by Roll20 OR '''Dungeons and Dragons 5E''' → D&D 5E by Roll20<br />
<br />
<br />
If you want to add a character sheet to an existing campaign, you can find this drop down menu once again by accessing the [[Game Settings Page]] from the [[Game_Management#Game_Details_Page|Game Details]]-page.<br />
<br />
{{mbox | text = '''NOTE:''' If you have added custom attributes to your character journals prior to adding a character sheet to a campaign, you may want to delete them first. Adding a character sheet to a campaign will create its own set of custom attributes on all of your character journals, but it will reuse any attributes encountered if they share the same name. This can cause calculation issues on the sheet.}}<br />
<br />
<br />
If you were previously using either the [[DnD5e Shaped Character Sheet|D&D 5E (Shaped)]] or [[DnD5E_Community_Contributed|D&D 5E (Community Contributed)]] sheets and wish to transfer over to the '''D&D 5E by Roll20''' version, it's a good idea to ask help on the [https://app.roll20.net/forum/category/277980 forums].<br />
<br />
<div style="clear: both"></div><br />
<br />
==Where to Find the Sheet==<br />
Once a character sheet has been added to a game, and once inside it, on all [[Journal#Characters|Characters Journals]], a new tab will be available between the '''“Bio & Info”''' and '''“Attributes & Abilities”''' tab labelled '''“Character Sheet”'''. Much like the Attributes & Abilities tab, only players who have been granted Edit permissions for the journal entry will be able to access the Character Sheet tab.<br />
<br />
''See also:'' '''[[Add_character_sheet#Adding_New_Characters_In-Game|Create new character sheets to your players]]'''<br />
<br />
==Sheet Features==<br />
The '''D&D 5E by Roll20''' sheet has all of the functionality of a pen and paper character sheet, and much more. Certain aspects of the sheet have been streamlined or automated to remove bookkeeping and speed up gameplay. The key features are auto-calculations, [[Macro|macro]] buttons, and [[D&D 5e by Roll20 Roll Templates|roll templates]]. The sheet defaults to using the rules as printed in the D&D 5E SRD, however it's dynamic enough to allow you and your group to use many custom house rules you might want.<br />
<br />
===Auto Calculations===<br />
Many parts of the sheet use auto calculations to fill in derived attributes with the expectation that you're using the rules as printed in the 5th Edition SRD. Many of these calculated traits can be modified from the character sheet's <span style="font-family:Pictos;">y</span> [[D&D 5E by Roll20#Settings Page|Settings]]-tab, and those set by Sheet Workers can be edited directly. Below are some examples of Sheet Worker and Auto Calculation functionality:<br />
<br />
* '''Class''' - Changing the character's class from the header will automatically update the character's saving throw proficiencies, their hit die type, spell casting ability, and spell save DC. <br />
* '''Level''' - Changing the character's level will also update their proficiency bonus, number of spells per day, and more.<br />
* '''Attributes''' - Changing one of the character's attributes will also update the related modifier, skills that are based on that attribute, and derived stats such as initiative or passive perception.<br />
<br />
===Roll Buttons and Roll Templates===<br />
[[File:5E_OGL_Sheet_Rollable_Buttons.gif|right|frame|Any label that highlights in red when the mouse hovers over it is rollable.]]<br />
''Main Page:'' '''[[D&D 5e by Roll20 Roll Templates|D&D 5E by Roll20 Roll templates]]'''<br />
<br />
Most of the stats in the game can be rolled by hovering over their name, the stat will turn red, and then left-clicking the mouse. This is true for Attributes, Saves, Skills, Hit Dice, Death Saves, Tool Proficiencies, Attacks & Spellcasting, Spell Cards, and NPC Actions/Attacks. Any of these roll buttons can be dragged directly from the sheet to your [[Macro Quick Bar]], enabled from the <span style="font-family:Pictos;">y</span> [[My Settings]]-tab of Roll20's [[Sidebar]].<br />
<br />
Player characters have both a simple and attack [[D&D 5e by Roll20 Roll Templates|roll template]] that is output to the {{Text Chat}}-tab on the right hand [[Sidebar]]. The simple template is used for everything except for attacks. The attack template is shaped to show up in three pieces; the attack at the top, information in the middle, and damage at the bottom. Depending on your sheet settings, the damage will not roll automatically unless you click on the name of the attack from the roll template in the chat tab. This was designed to simulate the tabletop experience of rolling to attack and then rolling damage if necessary. You can change this behavior in the sheet <span style="font-family:Pictos;">y</span> [[D&D 5E by Roll20#Settings Page|Settings]]-tab, tab under "Auto Damage Roll".<br />
<br />
<div style="clear: both"></div><br />
<br />
====Rolling for Advantage and Disadvantage====<br />
With the '''D&D 5E by Roll20''' Sheet, the [[D&D 5E by Roll20#Settings Page|default sheet settings]] has Advantage set to ''always'' rolled for convenience purposes. It is commonly agreed upon that a gaming group uses the left roll result when advantage is not being used for a check. When advantage or disadvantage is in play, simply choose the higher or lower result among the two per usual. You can change this behavior in the sheet <span style="font-family:Pictos;">y</span> [[D&D 5E by Roll20#Settings Page|Settings]]-tab (gear icon at the top right of the page), tab under "Roll Queries". You have the choice of "Always Roll Advantage" (the default setting), "Advantage Toggle", "Query Advantage", or "Never Roll Advantage".<br />
<br />
'''Advantage Toggle:''' The Advantage Toggle will add three buttons to the top of your character sheet: "Advantage", "Normal", and "Disadvantage". You can click on any of these to roll for Advantage (the highest roll result will highlight in black), Disadvantage (the lowest roll result will highlight in black), or a single d20.<br />
<br />
'''Query Advantage:''' The Query Advantage setting will prompt a dialog box to appear whenever you roll from your sheet. It will ask you to select what sort of roll want to do (Normal, Advantage, Disadvantage). After choosing the type you want, the roll will occur in chat.<br />
<br />
'''Never Roll Advantage:''' When rolling from your sheet, only a single d20 will be rolled.<br />
<br />
===Resizable Text Fields===<br />
[[File:5E_OGL_Sheet_Resizable_Text_Fields.gif|right|frame|Making a text field larger is just a matter of click and dragging.]]There are many free-text fields on the sheet that give you a place to keep information that doesn't necessarily follow a specific format. All of the fields on the Bio Tab are free-text fields as well as the Description fields present for attacks, spells, equipment, features & traits, and NPC actions. If your text overflows past the bottom of a text field, you can resize it to view the content in its entirety by clicking and dragging the bottom right corner icon shown in the adjoining image.<br />
<br />
<br />
At present, these fields can only contain raw text. There are no formatting options (bold, italic, etc.) available.<br />
<br />
<div style="clear: both"></div><br />
<br />
===The Padlock Button and Organizing Elements===<br />
(aka. '''[[Character_Sheets#Repeating_Section|Repeating Section]]''')<br />
[[File:5E_OGL_Sheet_Padlock.gif|right|frame|The Padlock Toggle]]There is a <span style="font-family:Pictos;">(</span> (padlock) icon set at the bottom of several different fields of the '''D&D 5E by Roll20''' Sheet. It is used where a player is meant to add entries such as individual attacks, actions, pieces of equipment, features & traits, tool proficiences & custom skills, other proficiencies & languages, and spells. This icon behaves as a toggle button. <br />
<br />
When set in the <span style="font-family:Pictos;">(</span> locked position (default), a player can add new entries into the field. When the button is toggled to <span style="font-family:Pictos;">)</span>(unlocked), a player can no longer add new entries, but they will be able to reorder or delete any of the existing ones. The <span style="font-family:Pictos;">#</span>(red trash bin)-icon overlaid on the right hand side of the entry will delete it.<br />
<br />
{{Ambox<br />
|nocat=true<br />
| type = content<br />
| text = '''Deleting an entry cannot be undone!''' On left side of every entry while the padlock is <span style="font-family:Pictos;">)</span> unlocked is a re-sort icon symbolized by '''<big>≡</big>'''(three parallel lines). By clicking and dragging on this icon, you can rearrange the order of the entries in the field.<br />
}}<br />
<br />
{{Ambox<br />
|nocat=true<br />
| type = content<br />
| text = Some of the features of '''Repeating Sections''' do not work when the [[Character_Sheets#Character_Sheet_in_a_separate_window|Character Sheet is in a separate window]].<br />
}}<br />
<br />
<br />
<div style="clear: both"></div><br />
<br />
==Utilizing the 5th Edition SRD Compendium==<br />
[[File:5E_OGL_Sheet_Compendium.png|right|The Compendium Tab]]Upon adding the D&D 5E by Roll20 Character Sheet to a campaign, the [https://app.roll20.net/compendium/dnd5e/BookIndex| 5th Edition SRD Compendium] is automatically enabled for use from it's own <span style="font-family:Pictos;">i</span> [[Compendium]]-tab in the '''[[Sidebar]]''' of the application. It's located between the {{Journal}} and <span style="font-family:Pictos Custom;">u</span> [[Jukebox]]-tabs, and is accessible for both GM and Player alike.<br />
<br />
<br />
The <span style="font-family:Pictos;">i</span> [[Compendium]] allows for rapid searching of all rules, classes, monsters, spells, items, and more that are included in the 5th Edition SRD. This minimizes time spent for the gaming group to leaf through a book in the middle of a session for a rule clarification. Even better, both the GM and the Player can utilize dragging and dropping* from the <span style="font-family:Pictos;">i</span> [[Compendium]]-tab directly to your character sheets. This makes statting NPCs and PCs far faster than inputing everything manually.<br />
<br />
{{mbox | text = '''NOTE:''' The 5th Edition SRD is similar but NOT identical to the ''Dungeons and Dragons'' 5th Edition Rule Book. Some skills, classes, creatures, items, and other elements found within the ''Dungeons and Dragons'' rule book are strictly intellectual property of Wizards of the Coast and not accessible through their Open-Game License(OGL).}}<br />
<br />
<br />
===Statting PCs===<br />
Dragging from the <span style="font-family:Pictos;">i</span> [[Compendium]] works for the Equipment and Spell fields of the PC Sheet. This will not only carry over the name of the item or spell, but the relevant attack and damage rolls and any rules or flavor text that comes with it. Adding Compendium items in this fashion also automatically adds the equipment item (if it's a weapon) or spell to the Attacks & Spellcasting field to roll directly from. Items that modify a character's Attributes, Saves, AC, To Hit, Damage, Spell Attacks, and Spell DC will be automatically calculated on the sheet when dragged in. For example, if a Belt of Giant Strength is dragged to a sheet, the strength Attribute Score will become highlighted in blue and its attribute score will be increased. An asterisk is appended to the right of the score to also signify that it has been modified by an item. When you mouse over this number, the strength Attribute Score will revert back to what its unmodified total so you can refer back to it. Dropping a Compendium items that is an ammunition type (arrows, crossbow bolts, blowgun darts, etc) will automatically fill out a resource field for that item and link it to its entry in the Equipment section.<br />
<br />
To insert a Compendium item into the character sheet, run a search for the Item or Spell you want to add in the <span style="font-family:Pictos;">i</span> [[Compendium]]-tab. Once found, click and drag on the Compendium item's name so that it creates a little named tile that follows along with your mouse. Drag this over to the character sheet, it doesn't matter where. A text box that reads, "ACCEPTING DROP FROM COMPENDIUM" will appear on your sheet if this is done correctly. Let go of the tile and the entry will be auto-completed with all the data pertaining to the the Compendium entry in the correct location on the sheet. You can see this in action below under [[#Equipment|Equipment]].<br />
<br />
===Statting NPCs===<br />
You can fill out an entire NPC sheet in a single drag and drop. Run a search for the NPC you want to create from the <span style="font-family:Pictos;">i</span> [[Compendium]]-tab. Once found, click and drag on the NPC name so that it creates a little named tile that follows along with your mouse. Drag this to anywhere over the Tabletop area of the screen. Let go of the tile and a new character journal will be created named after the NPC from the Compendium entry. Its sheet will be changed over to the NPC sheet and filled with the entire NPC entry from the Compendium including their Actions, Reactions, and Legendary Actions if applicable. If you're using one of the Compendium expansions bought from the Roll20 Marketplace like the Monster Manual or Volo's Guide to Monsters, token art will also be pulled from the Compendium entry, placed on the table, and linked to your NPC's journal.<br />
<br />
You can also drag an NPC entry from the Compendium to an existing journal entry if you have the sheet open. If the sheet is in PC sheet mode, it will automatically change it over to the NPC sheet, and add its entry elements to it.<br />
<br />
One thing to note about dragging a stat block over from the Compendium is that it uses an ''additive'' behavior. It will not replace anything that you have already entered manually.<br />
<br />
=The PC Sheet=<br />
The '''D&D 5E by Roll20 Sheet''' contains both the PC Sheet ''and'' the NPC Sheet. By default, a new character journal is set to the PC sheet, but you can switch between the two by toggling it from the [[#Settings Page|General Options Settings]]. The PC Sheet is split up into four pages and can be selected from the buttons just underneath the header at the top of the sheet. They are listed from left to right order: The [[#Core Page|Core Page]], The [[#Bio Page|Bio Page]], The [[#Spells Page|Spells Page]], and The [[#Setting Page|Setting Page]].<br />
<br />
== Creating and Leveling up a character with Charactermancer ==<br />
Players and GMs using the '''D&D 5E by Roll20''' Sheet can use the Charactermancer to create and level up characters.<br />
<br />
'''How to use the Charactermancer for [[Charactermancer (D&D Fifth Edition)|character creation and leveling]].'''<br />
<br />
<br />
{{Ambox<br />
|nocat=true<br />
| type = content<br />
| text = The Charactermancer do not work when the [[Character_Sheets#Character_Sheet_in_a_separate_window|Character Sheet is in a separate window]].<br />
}}<br />
<br />
==Core Page==<br />
[[File:5E_OGL_PC_Core_Guide.jpg|right|frame|The Core Page]]The Core Page is selected by default and has most of the information you'll want to use on a regular basis to play your character. This should look very similar to the content you would normally find on the first sheet of the physical "D&D 5E by Roll20" player character sheet. The screenshot at the top of this wiki page displays the entirety of the Core Page. <br />
===(1) Core Header===<br />
[[File:D&D5E-Roll20-core-header.png|550px]]<br />
<br />
The header block at the top of the sheet changes based on the page you have selected. On the Core page you can select a class by its dropdown menu. The available options from the dropdown are: Barbarian, Bard, Cleric, Druid, Fighter, Monk, Paladin, Ranger, Rogue, Sorcerer, Warlock, and Wizard. You can create a custom class from the Settings Page.<br />
<br />
Once a class has been selected you can update the class's level by changing the number next to the class. The sheet will also automatically mark the abilities that class has proficiency in as well as automatically select the dice that will be used when Hit Dice are rolled. You can change the Hit Dice setting manually from the options menu. If your character multi-classes, then the secondary class and its level will appear beside the primary class. This Class and Level field can hold up to four classes if desired.<br />
<br />
The fields for Background, Race, Alignment, and Experience Points allow you to fill in whatever text you wish to put in them. The Character Name persists over all pages of the sheet and is tied to the name you give to the journal entry. Changing it on the sheet itself will also change the name on the character journal and vice versa once it is closed.<br />
<br />
===(2) Attributes===<br />
<br />
[[File:5E_OGL_Sheet_Attribute_Block.jpg|left]]Along the left side of the sheet are listed the 6 primary attributes: Strength, Dexterity, Constitution, Intelligence, Wisdom, and Charisma. These attributes are used by almost every other calculation on the sheet, as they are the core definition of a character. Each attribute block has the core attribute score, which can be changed by modifying the number in the oval at the bottom of each block, and, inside the square, the attribute modifier which is auto-calculated based on the score below it. All racial ability score increases must be manually added to the core attribute score using the settings "gear" symbol at the top of the page (where the Core, Bio, and Spells buttons are located.) The attribute modifier uses the following calculation to set the value:<br />
<br />
<br />
<code>[[floor((@{strength}-10)/2)]]</code><br />
<br />
The attribute can be referenced by its name, such as @{dexterity} while the attributes modifier can be referenced by adding the mod suffix, @{dexterity_mod}.<br />
<br />
<div style="clear: both"></div><br />
<br />
===(3) Inspiration===<br />
<br />
[[File:D&D5E-Roll20-inspiration.png|left]]You can track whether or not you have Inspiration by clicking the circle next to the Inspiration block at the top left of the Core page. This will toggle a dragon spiral icon on and off for indication purposes.<br />
<br />
<div style="clear: both"></div><br />
<br />
===(4) Proficiency Bonus===<br />
<br />
[[File:5E_OGL_Sheet_Proficiency.png|left]]Your character's proficiency bonus is listed near the top left of the page. You cannot modify this value manually, instead it is automatically set based off your character's over-all level. Your character's Level can be set by changing the number next to your Class name in the [[#header_info|Header]] at the top when on the Core page.<br />
<br />
<div style="clear: both"></div><br />
<br />
===(5) Saving Throws===<br />
<br />
[[File:5E_OGL_Sheet_Saving_Throws.png|left]]Next to the core Attributes on the left side of the page is a list of the same attributes to be used in making saving throws. To mark an attribute that your character has proficiency in for saving throws, check the box next to the appropriate attributes. When you select a class in the header section of the Core page it will automatically check the correct boxes for that class's proficiencies.<br />
<br />
You can add an additional field to Saving Throws to serve as a Global Save Modifier. An example is if the character is under the influence of the Bless spell and can roll a 1d4 in addition to the result of their saving throws. This is enabled from the Settings Page under General Options. Once enabled a seventh checkbox and field will be added at the bottom of the Saving Throws block with a text field to enter the additional die roll. For this example, you could enter "1d4[BLESS]" in the global checkbox's text field that you can enable when the character is under the effects of the Bless spell. The word between the brackets becomes a label that can be seen when you mouse over the roll result in chat. While this Global Save Modifier is checked, every roll made from the Saving Throws block and performing a Death Save will add this modifier to the result.<br />
<br />
<div style="clear: both"></div><br />
<br />
===(6) Skills===<br />
[[File:5E_OGL_Sheet_Skills.png|left]]<br />
To the right of the Core Attributes is a list of all of the character's Skills. Each skill can be rolled by clicking on the skill name. If you have proficiency in a specific skill, then you would check the box next to the skill name, this will automatically add your proficiency bonus to that skill's checks. Each skill also lists the core attribute, that is used in the roll calculations, next to it in parenthesis.<br />
<br />
You can set advanced skill options for the Settings page, such as skill expertise, flat bonuses from class archetypes or feats, as well as Jack of All Trades.<br />
<br />
<div style="clear: both"></div><br />
<br />
===(7) Armor Class, Initiative, & Speed===<br />
<br />
[[File:D&D5E-Roll20-AC-Init-Speed.png|left]]The Armor Class & Speed blocks at the top center of the page can be used to keep track of your Armor and Speed values. The Initiative block cannot be modified manually, but instead is auto-calculated based off your character's Dexterity. If you have any additional initiative modifiers you can add them on the {{gear}} [[#Settings Page|Settings Page]] under Initiative Modifier in the Class Options block.<br />
<br />
Armor Class can also be tracked automatically by using the [https://app.roll20.net/compendium/dnd5e/BookIndex Compendium] compatible inventory, on by default.<br />
<br />
You can configure a custom AC calculation using the {{gear}} [[#Settings Page|Settings Page]] under the Attribute Tracking section. It's listed as "Armor Class Tracking" and is set to "Automatic" by default. If you select Custom, you can select up to two different attributes to apply to the character's armor class.<br />
<div style="clear: both"></div><br />
<br />
====Using the Global AC Modifiers====<br />
If you check the "Show Global AC Modifier" field in the character sheet General Options settings, the sheet will display a repeating section to configure and apply different modifiers to AC. So, for example, if your character has a common bonus, such as from a spell or a conditional feat or fighting style, you can toggle that AC bonus from the character sheet directly.<br />
<br />
====Rolling for Initiative and the Turn Order Tracker====<br />
Clicking on the word INITIATIVE will roll that character's initiative score. If your players have [[Token|tokens]] linked to their character sheets, they can roll their initiative ''and'' simultaneously add their character and its initiative score to the {{Turn Tracker}} automatically. What is required of the player is that their linked token must be currently selected on the Tabletop before they roll off their sheet.<br />
<br />
If you would like to enable a tie breaker component to Initiative, there is an option to enable this from the [[#Settings Page|Settings Page]] under the "Attribute Options" block. What this does is that it will add your dexterity Attribute Score as a decimal value to your Initiative. So if you have a character with a dexterity attribute score of 14, your initiative modifier will change from a <code>2</code> to a <code>2.14</code>.<br />
<br />
===(8) Hit Points & Temporary Hit Points===<br />
[[File:5E_OGL_Sheet_HP.png|left]]The Current Hit Points and Temporary Hit Points blocks are used to keep track of your character's Hit Points (HP). Inside the Current Hit Points block, at the top, is a line that lists the character's maximum amount of HP. <br />
<br />
<br />
When your character takes damage, if they have any, it should be subtracted from their Temporary Hit Points first, then any remaining damage would then come off of the character's Current Hit Points.<br />
<br />
<div style="clear: both"></div><br />
<br />
===(9) Hit Dice===<br />
[[File:5E_OGL_Sheet_Hit_Dice2.png|left]] The Hit Dice block is used to keep track of and roll your character's hit dice. Inside the Hit Dice block, at the top, is a line to keep track of the total number of dice your character can have. In the main area of the block you would keep track of the remaining hit dice. Clicking the "HIT DICE" label will roll the hit dice for your selected class automatically. If you wish to change the dice that is rolled you can do so in the Class Options section of the [[#Settings Page|Settings Page]] ({{gear}} icon). <br />
<br />
<br />
If your character is multi-classed, when rolling your hit dice (by clicking "''HIT DICE''", a pop-up will ask which of your character's current class's hit dice you want to roll. This input accepts only numerals a input to make automatic tracking of the [[API:A Guide to the API|API]] possible.<br />
<div style="clear: both"></div><br />
<br />
===(10) Death Saves===<br />
[[File:5E_OGL_Sheet_Death_Saves.png|left]]The Death Saves block is used to keep track of your character's death save rolls once they have been knocked out. You can click the "DEATH SAVES" label to make a death save roll. If you roll greater than 10 you would check one of the boxes next to "Successes" otherwise you would check a box next to "Failures". If your character has any modifiers to their death save rolls they can be added in the Class Options section of the Settings Page(gear icon).<br />
<div style="clear: both"></div><br />
<br />
===(11) Attacks & Spellcasting===<br />
[[File:5E_OGL_Sheet_Attacks_And_Spellcasting.png|left]]The Attacks & Spellcasting block in the center of the Core page of this character sheet will be one of the most often used sections. To start, you can manually add any attack or spell to this section by hovering over the block and clicking the "Add" button(the <span style="font-family:Pictos;">&</span> symbol). This will open a form that can be filled out with all of the information about the specific attack or spell you are adding. <br />
<br />
<br />
This section will automatically add attacks, with all the stats, for spells that have an attack component when they are added to your spell sheet on the [[#Spells Page|Spells Page]]. This happen both if you add the spell manually or if you drag and drop a spell from the <span style="font-family:Pictos;">i</span> [[Compendium]]. An attack is also automatically created if you drag and drop an item from the Compendium into your sheet.<br />
<br />
<div style="clear: both"></div><br />
[[File:Poisoned Dagger 5e Attack.png|right|frame|An example of an attack form filled out for a physical attack using a +1 Poisoned Dagger]]For example, lets say Erin the Bold has a +1 Poisoned Dagger that has the stats of a regular dagger, but also metes out an additional 1d6 of poison damage alongside the typical 1d4 points of piercing damage. The image displayed to the right is how the attack would be set up:<br />
<br />
<br />
Since this is a [https://app.roll20.net/compendium/dnd5e/Items:Dagger#h-Dagger dagger], and daggers have the "[https://app.roll20.net/compendium/dnd5e/Weapons#h-Weapons Finesse]" attribute I can chose either STR or DEX for my bonus attribute. Erin is quicker than she is strong, so we will pick DEX as the attribute to attack with, as well as checking the "proficient" checkbox since Erin is experienced with using these sorts of weapons. She doesn't have any other gear that might make her attacks better, so we will leave the generic bonus between the attribute and proficiency blank, or 0. Being a +1 Poisoned Dagger means that it is also magical, so it gets a 1 in the magic bonus slot just below. A dagger can also be used as a thrown weapon, so we've added the weapon's throwing range info to the "Range" field. Since a weapon does damage, we have checked the first "Damage" checkbox and filled in the required fields. This dagger does 1d4 piercing damage + Erin's DEX mod + 0 bonus damage (this would be used for bonus damage on top of the magical +1) and it doesn't have anything to change the critical damage so we just put the same damage into the "crit" box. Because this dagger can also cause poison damage, we also check the second "Damage" checkbox and fill in the info for the 2nd set of damage. The poison does a flat 1d6 poison with no extra bonuses, so we've selected "-" to say there is no attribute that adds to this damage. This damage also doesn't have anything to make the crit different so we set that to 1d6 as well. There are no extra saving throws or effects that are included with this attack, so we leave these additional sections blank. <br />
<br />
These additional effect sections will be used more commonly with spells, like [https://app.roll20.net/compendium/dnd5e/Fireball#h-Fireball Fireball], where you would require a DEX save against your SPELL DC, which will be set according to your character's spell casting level. For a fireball, the save effect would be "half damage" and the "Description" would be something like "Hits all creatures within 20 ft of the explosion point".<br />
<br />
After you are done modifying all of individual stats for an attack you can click the gear icon at the top right of that section and it will hide the stats for that attack. If ever you need to change these stats in the future you can hover over the entry and click the <span style="font-family:Pictos;">y</span>(gear)-icon that shows up to unhide the stats section. <br />
<br />
<div style="clear: both"></div><br />
====Adding Global Attack and Damage Modifier====<br />
You can add two special entries to the Attacks & Spellcasting block to handle to global Attacks and Damage modifications to rolls. An example is if the character is under the influence of the Bless spell and can roll a 1d4 in addition to the result of their attack roll. This is enabled from the [[#Settings Page|Settings Page]] under General Options. Once enabled, a checkbox will be added at the bottom of the Attacks & Spellcasting block with a text field to enter the additional die roll. For this example, you could enter <nowiki>"1d4[BLESS]"</nowiki> in the global checkbox's text field that you can enable when the character is under the effects of the Bless spell. The word between the brackets becomes a label that can be seen when you mouse over the roll result in chat. While these Global Modifiers are checked, every roll made from the Attacks & Spellcasting block will add these modifiers to the result.<br />
<br />
====Rolling from the Attacks & Spellcasting Block====<br />
[[File:Poisoned Dagger 5e Roll.png|frame|An attack roll from a +1 Poisoned Dagger]]Rolling from the Attacks & Spellcasting Block is no different than rolling from any other portions of the character sheet. Hovering your mouse over any entry here will highlight its entire label (NAME, ATK, and DAMAGE/TYPE) in red and you'll be able to click on it to roll the attack or spell. You can also drag this entry into the Macro Bar to give yourself easy access to this attack. Because this is a repeating section, the macro name will be a bit messy, but you can right-click the button and rename the macro to whatever you like.<br />
<br />
With any attack that checks for AC, you will see TWO rolls set side by side for the Armor Class check with the name of the attack listed underneath them with the Attack modifier bonus (ATK) appended to the Attack name in light grey. The Roll20 D&D 5E Character Sheet ''always'' rolls for Advantage by default, so you will always have two roll results for this check (most gaming groups use the left roll result if neither Advantage or Disadvantage is being factored in the check). If there is a specified range for the attack, this will be listed above the attack's name.<br />
<br />
Underneath the AC Check and Attack Name is the Damage roll result for the attack. Underneath this roll result will be the Damage Type (ex. slashing, piercing, poison, fire, etc.) listed in light grey italicized font.<br />
<br />
For spells that don't check for AC and instead require a Saving Throws to mitigate or negate the spell's effect, the SPELL DC is listed first. Underneath this, in italicized font, is the effect if a character succeeds the check listed. Underneath the effect is the required attribute saving throw that must be rolled. If Damage is applied, this result is rolled and listed next with its Damage Type.<br />
<br />
[[File:5e_attack_example.gif|right|frame|How to view attack damage when the sheet is set to "Don't Auto Roll Damage"]]<br /><br />
<br />
<br />
{{mbox | text = '''NOTE:''' If your character sheet's Settings have "Auto Damage Roll" set to "Don't Auto Roll Damage" under General Options, the damage will not be listed underneath the AC roll result in chat. The damage was rolled, but presently hidden from view. Anyone can see the damage delivered by manually unfolding the roll result open by hovering your mouse over the roll result in chat and clicking on the attack/spell's name.}}<br />
<div style="clear: both"></div><br />
<br />
===(12) Personality Traits, Ideals, Bonds, and Flaws===<br />
These text fields lock to prevent accidental edits. When a sheet is first created, these fields are unlocked and given a dashed yellow border to the top of the field to showcase that they're editable. To lock the field after entering text, click on the gear icon in the upper right corner of the field. This will remove the yellow border and the field will conform in height to display everything within it.<br />
<br />
There presently isn't a means to format the raw text (italicize, bold, font alignment, etc) within these fields and any line breaks are stripped out. If you ever need to edit the content again while the field is locked, mouse over the desired field and the gear icon will reappear in the top right. Clicking on that will unlock the field once again for edits.<br />
<br />
===(13) Class & Other Resources===<br />
[[File:5E_OGL_Sheet_Resources.png]]<br />
<br />
The Class & Other Resource Blocks can be used to keep track of either an item quantity you have in your equipment (like arrows in a quiver), or skills that don't fit into the other sections on the sheet (like a '''Sorcerer's Sorcery Points''', a '''Cleric's Channel Divinity''' at higher levels, or the number of rounds a '''Barbarian''' has been '''Raging''' so far in a combat encounter).<br />
<br />
There are 3 fields per Block:<br />
* Resource Max:<br />
** The Resource Max field is a text box which allows you to quantify exactly what you're tracking (ex. "Total: 10 Rounds").<br />
* Resource:<br />
** The Resource field is a numeral that you dial up or down or input directly.<br />
* Resource Name:<br />
** The Resource Name is a text box that allows you to label the resource when you click on the light grey "OTHER RESOURCE" label to overwrite it with your own.<br />
**"OTHER RESOURCE" is placeholder text<br />
<br />
<br />
A resource block will be filled automatically if you checkmark an Equipment item as "USE AS A RESOURCE" & the Item Quantity field will be paired with the Resource field in the Resource block & vice versa (you'll need to click outside of the field or hit Enter for changes to refresh across the sheet). If the two resource blocks given by default are not enough then you can add additional blocks by hovering over the section & clicking the "Add" (+ symbol) button.<br />
<br />
The Item Name will also be added to the Resource Name field, however the Resource Max field is apparently not linked to the Item currently.<br />
<br />
If you drag & drop an ammunition item type from the Compendium into your character sheet, the item is added to the Equipment block & is automatically listed & linked as an Other Resource.<br />
<div style="clear: both"></div><br />
To call the first set of class resources use:<br />
* Class Resource <code>@{class_resource}</code><br />
* Other Resource <code>@{other_resource}</code><br />
<br />
<br />
To call the Repeating resources use<br />
* Repeating Resource 1st left<code>@{repeating_resource_$0_resource_left}</code><br />
* Repeating Resource 1st right<code>@{repeating_resource_$0_resource_right}</code><br />
* Repeating Resource 2nd left<code>@{repeating_resource_$1_resource_left}</code><br />
* Repeating Resource 2nd right<code>@{repeating_resource_$1_resource_right}</code><br />
* etc.<br />
<br />
<br />
If you want to do a basic Full Readout of the Repeating Resource, the Format would be (Top Left to Bottom Right):<br />
* Class: <code>@{class_resource_name}: @{class_resource} / @{class_resource|max}</code><br />
* Other: <code>@{other_resource_name}: @{other_resource} / @{other_resource|max}</code><br />
* Left 0: <code>@{repeating_resource_$0_resource_left_name}: @{repeating_resource_$0_resource_left} / @{repeating_resource_$0_resource_left|max}</code><br />
* Right 0: <code>@{repeating_resource_$0_resource_right_name}: @{repeating_resource_$0_resource_right} / @{repeating_resource_$0_resource_right|max}</code><br />
* Left 1: <code>@{repeating_resource_$1_resource_left_name}: @{repeating_resource_$1_resource_left} / @{repeating_resource_$1_resource_left|max}</code><br />
* Right 1: <code>@{repeating_resource_$1_resource_right_name}: @{repeating_resource_$1_resource_right} / @{repeating_resource_$1_resource_right|max}</code><br />
* etc.<br />
<br />
===(14) Tool Proficiencies===<br />
[[File:5E_OGL_Sheet_Tool_Proficiencies.png|left]]The Tool Proficiencies block is for listing a character's Tool Proficiency skills. At the bottom of this block is an "Add" (<span style="font-family:Pictos;">&</span> symbol) button. Clicking this will add a new entry to this block where you can add all of the relative stats for a specific tool proficiency, say Woodcarver's Tools. You can set the level of proficiency to either Proficient, Expertise, or Jack of All Trades. The roll bonus for that tool will reflect the proficiency level selected. Next is an Attribute drop down menu where you can select which character attribute to roll with for a proficiency check. One of the options you can choose is "QUERY ATTRIBUTE" which when you click on the Tool Proficiency to roll it, you will be prompted to choose which attribute you would like to use. The attribute used for the check will be up to the GM when it is time to make the roll check. If there is any additional bonus modifiers that come along with the tool in question, you can input it in the "MODS:" field.<br />
<br />
Once you finished filling out the stats for this tool you can click the <span style="font-family:Pictos;">y</span>(gear) icon at the top right of the entry to hide the stat fields and leaving behind just the rollable button. You can roll by either clicking on this rollable button or dragging it to your [[Macro Bar]].<br />
<br />
You can also use this section to create custom skills or rolls for your campaign setting or home-brew ruleset. Check out the [[#Custom Skills and Stats|Advanced Use]] section for further details.<br />
<br />
====Global Skill Modifier====<br />
You can add a special entry to the Tool Proficiencies & Custom Skills block to handle to global Attacks and Damage modifications to rolls. An example is if the character is under the influence of the Guidance spell and can roll a 1d4 in addition to the result of their skill check. This feature is enabled from the [[#Settings Page|Settings Page]] under General Options. Once enabled, a checkbox will be added at the bottom of the Tool Proficiences & Custom Skills block with a text field to enter the additional die roll.<br />
<br />
For this example, you could enter "1d4[Guidance]" in the global checkbox's text field that you can enable when the character is under the effects of the Guidance spell. The word between the brackets becomes a label that can be seen when you mouse over the roll result in chat. While this Global Modifier is checked, every roll made from the Tool Proficiencies & Custom Skills block and the Skills block will add this modifier to the result.<br />
<div style="clear: both"></div><br />
<br />
===(15) Other Proficiencies & Languages===<br />
[[File:5E OGL Sheet Proficiencies.png|left]]<br />
This block can be set up to be Compendium Compatible (where you can add repeating sections for individual items) or as one resizable free-text field to enter whatever you wish in here. If you don't feel the Tool Proficiency block is needed (as in, you don't feel like your party will ever have to roll individual tool sets), you can store a character's Tool Proficiencies here instead. There presently isn't a means to format the raw text (italicize, bold, font alignment, etc). You can adjust this block's behavior by going to the Settings Page of the sheet and going to the General Options block to change whether this block uses the Simple or Compendium Compatible layout.<br />
<br />
When the Other Proficiences & Languages block is made Compendium Compatible, each repeating field lists a Type selection field and a Proficiency text field. Type has the following options available from its drop down selection menu: Language, Weapon, Armor, Other. <br />
<p style="clear:both;"></p><br />
<br />
===(16) Equipment===<br />
[[File:5E OGL Sheet Equipment.png|framed|right|The Equipment block of the PC Sheet]]<br />
The Equipment block at the bottom of the page has 2 different versions: a Simple version that features a single plain text field where you can track all of your equipment in any format you wish and a Compendium Compatible version that allows you to drag and drop items from the Compendium to automatically populate repeated sections for each indivdual piece of equipment.<br />
<br />
To swap between the two different Equipment block versions, first, go to the sheet's Settings Page (gear icon at the top right of the page) and then to the "General Options" section. Here, on the field labeled "Inventory", you can select between "Simple" or "Compendium Compatible" respectively. Like the name implies, if you want to be able to copy items directly from the Compendium using drag and drop, you must use the Compendium Compatible version. Dragging item entries from the Compendium to the character sheet will add it fully filled in the Equipment section as well as other automated actions described below.<br />
<br />
====Automated Compendium Functionality====<br />
If you populate the Equipment block by dragging and dropping <span style="font-family:Pictos;">i</span> [[Compendium]] items, there are several automatic features that occur when the entries you drag in our equipment items.<br />
Auto-Equip: Every item dragged to the sheet is automatically equipped in the Equipment Section<br />
*'''Weapons:''' A weapon dragged in from the Compendium will add an attack in the Attacks and Spellcasting section for that item.<br />
*'''Armor:''' Armor that is dragged in from the Compendium will add its bonus to the Armor Class (while equipped) section. If you drag multiple pieces of armor to the same sheet and at least two armor entries are equipped at once, a warning will pop up in red at the top of the Equipment Block that the Armor Class isn't being correctly calculated because of the bonus overlap. This warning will dissapear when you unequip down to a single set of armor.<br />
*'''Magical/Wondrous Items:''' Items that modify Attributes, Saves, AC, To Hit, Damage, Spell Attacks, and Spell DC will add that bonus to those elements on the sheet. In most cases, the attribute that is being modified will highlight in blue and followed with an asterisk to showcase that the attribute is being modified by an item. Mousing over the modified number will display the base value of that attribute before the item's modification is applied. This stat modification only applies if the item is equipped in the Equipment section and it will remove its bonus if it is unequipped.<br />
*'''Ammunition:''' Items dragged in from the Compendium that are used for ammunition such as arrows, bolts, darts, and slingstones, will automatically populate and link to an Other Resource field.<br />
<br />
====Manually Adding Items====<br />
You can also add items manually by hovering over the block and clicking the "Add" button (+ symbol). Each equipment entry, by default, show fields for quantity, name, and weight of an item. If you hover over a row and click the small "information" icon (grey-filled circle with a lowercase i centered in it) that appears at the bottom right of the entry you can also set some additional features. <br />
<br />
*'''Equipped Checkbox:''' The checkbox changes the appearance of the Item Name so it's easier to tell what your character currently has equipped from a glance. When left unchecked, the Item Name's font turns grey. When checked, the Item Name becomes a solid black.<br />
*Use As A Resource Checkbox: When checked, this will enable one of the Class Resource blocks and list the item name and its quantity within it. The quantity is tied between the two so changing it in one will be reflected in the other field after clicking outside the field.<br />
*'''PROP:''' This is a text field where you would take note of weapon properties such as ''finesse'', ''versatile'', or ''light''.<br />
*'''MODS:''' This is a text field where you would take note if an item (likely magical) would modify your stats in some fashion such as a character's Attributes, Saves, Skills, AC, To Hit, Damage, Spell Attacks, and Spell DC. If a stat is modified here, its attribute value will become highlighted in blue and adjusted by the supplied modifier listed here. An asterisk is appended to the right of the value to also signify that it has been modified by an item. While your mouse is hovering over the attribute, it will revert back to its unmodified total so you can refer back to its pre-moddified value.<br />
**The format for a stat modification is ''stat name:n'' where n is the stat bonus (ex. ''Strength:21'')<br />
*'''Description Field:''' This is a simple text field to include a description of the particular item and of any special qualities or effects it might have on the player.<br />
Some if not all of these fields will be filled in automatically when adding from the Compendium (where applicable).<br />
<br />
Both versions of the equipment field have the sections for each of the [https://app.roll20.net/compendium/dnd5e/Treasure#h-Treasure coins] you may find on your adventures: copper(CP), silver(SP), electrum(EP), gold(GP), and platinum(PP).<br />
<br />
====Encumbrance====<br />
If you are following Encumbrance rules, the <span style="font-family:Pictos;">i</span> [[Compendium|Compendium Compatible]] Equipment block will automatically calculate and track the weight of your character's backpack if you enter the weight values for any of the items in your Equipment list. When your character becomes encumbered, and depending on its severity, the words ENCUMBERED, HEAVILY ENCUMBERED, or IMMOBILE will display in red underneath the TOTAL WEIGHT value. You can also choose to follow Simple, Variant Encumbrance rules, or not follow Encumbrance rules at all by toggling it off on the [[D&D 5E by Roll20#Settings Page|Settings Page]] under "General Options".<br />
<br />
====Mods====<br />
The Mods field of each piece of equipment can modify the values of ability scores, AC, saving throws, Skill (Ability) checks and more. What follows is a list of the modifiers, and the proper syntax for adding them.<br />
<br />
All modifiers are separated by commas. There are other modifiers that can appear the mod field, used in creating the item from a compendium drag and drop operation, but the modifiers below have live effects on the character sheet, depending on if the item is marked as “equipped”.<br />
<br />
'''replace the <code>+n</code>, with the number you want.''' For example, if you want to boost Animal Handling skill by 3, you look at the table and find <code>Animal Handling +n</code>, so you will add to your item <code>Animal Handling +3</code>.<br />
<br />
{| class="wikitable" <br />
|-<br />
! Modifier<br /><br />
! Effect<br /><br />
|-<br />
| style="width: 20%;" | '''Combat Modifiers'''<br />
| '''These affect items that provide attacks (Appear in the attack section of the character sheet)'''<br />
|-<br />
| Melee Attacks +n<br />
| Adds +n hit "Magic Bonus" to that attack. It is not global, and only affects a weapon(melee or ranged), not an item, staff or other category. The bonus is figured into the attacks display on the 5e sheet.<br />It is NOT ''Melee Attack''.<br />
|-<br />
| Melee Damage +n<br />
| Adds +n damage "Magic Bonus" to that attack. It is not global, and only affects a weapon(melee or ranged), not an item, staff or other category. The bonus is listed separately in the attacks display on the 5e sheet.<br />
|-<br />
| Spell Attack +n<br />
| Adds a global +n to the character's Spell Attack bonus.<br />It is NOT ''Spell Attacks.''<br />
|-<br />
| '''Saving Throws'''<br />
| '''All modifiers stack with “Saving Throws +n'''<br />
|-<br />
| Strength Save +n,<br />Dexterity Save +n,<br />Constitution Save +n,<br />Intelligence Save +n,<br />Wisdom Save +n,<br />Charisma Save +n<br />
| Adds a +n to the indicated saving throw<br />''Do not use a colon.''<br />
|-<br />
| Saving Throws +n<br />
| Adds a Global Modifier to ALL saving throws.<br />
|-<br />
| Spell DC +n<br />
| Adds a global +n to a spell casting character’s Spell Save DC.<br />It is NOT Spell ''Save'' DC.<br />
|-<br />
| '''Ability Scores'''<br />
| <br />
|-<br />
| Strength +n,<br />Dexterity +n,<br />Constitution +n,<br />Intelligence +n,<br />Wisdom +n,<br />Charisma +n<br />
| Provides a bonus to the indicated ability score, which will appear in blue on the sheet while the bonus is active.<br />Do not use a colon. ''Strength: +10'' will do nothing<br />
|-<br />
| Strength n,<br />Dexterity n,<br />Constitution n,<br />Intelligence n,<br />Wisdom n,<br />Charisma n<br />
| Replaces the indicated ability score, which will appear in blue on the sheet while the bonus is active.<br />Do not use a colon. ''Strength: 10'' will do nothing<br />
|-<br />
| '''Skills'''<br />
| <br />
|-<br />
| Acrobatics +n,<br />Animal Handling +n,<br />Arcana +n,<br />Athletics +n,<br />Deception +n,<br />History +n,<br />Insight +n,<br />Intimidation +n,<br />Investigation +n,<br />Medicine +n,<br />Nature +n,<br />Perception +n,<br />Performance +n,<br />Persuasion +n,<br />Religion +n,<br />Sleight of Hand +n,<br />Stealth +n,<br />Survival +n<br />
| Adds the value to the indicated Skill roll. Note that in this case, the <code>+</code> and a colon are optional. <code>Acrobatics +5</code>, <code>Acrobatics 5</code>, <code>Acrobatics: +5</code>, <code>Acrobatics: 5</code> will all add <code>5</code> to the character’s Skill roll. For consistency and to guard against future functionality, it’s probably best to follow the format for ability scores, and use a plus sign with no comma: <code>Acrobatics +5</code>.<br />There is no Global Skill modifier<br />
|-<br />
| '''AC'''<br />
| <br />
|-<br />
| AC +n<br />
| By itself, <code>AC: 13</code> adds 13 to the character’s Armor Class. It does not replace it. <br /><br />If <code>Shield</code>, <code>Light Armor</code>, <code>Medium Armor</code>, or <code>Heavy Armor</code> is also in the mods field, it will change the calculation.<br />''<code>Light Armor, AC: 13</code>'' will give a formula of 13 + dex mod<br />''<code>Medium Armor, AC: 13</code>'' will give a formula of 13 + dex mod (max +2)<br />''<code>Heavy Armor, AC: 13</code>'' will give you flat AC 13<br />''Shield, AC: 13'' would add 13 to the your AC. The Shield keyword is superfluous in this case.<br />''<code>Shield, AC: 2</code>'' will just add 2 to the AC.<br />Finally, a bare modifier, such as for a Ring of Protection can just be written as <code>AC: +2</code> or <code>AC +1</code>.<br /><br />Shield or bare AC bonuses will stack with other armor mods on different items. You cannot equip multiple armors simultaneously, or have a custom armor equation on the settings tab and wear an armor. This will generate a flag.<br /><br />The + and a colon are semi-optional. <code>AC +5</code>, <code>AC: +5</code>, <code>AC: 5</code> will all work. However, <code>AC 5</code> will do nothing. For consistency and to guard against future functionality, it’s probably best to indicate a base AC as <code>AC: n</code> and a Shield as <code>AC +n</code>.<br />At this point, there is no way to differentiate between Ranged AC and Melee AC, though some magic items such as the ''Arrow Catching Shield'' make the distinction.<br />
|}<br />
<br />
<br />
<br />
<div style="clear: both"></div><br />
<br />
===(17) Features & Traits===<br />
[[File:5E OGL Sheet Features Traits.png|thumbnail|left|The Compendium Compatible itemized version of the Features & Traits section]]<br />
The '''Features and Traits '''-block is the place to store '''Class-''', '''Race-''' and '''Background Features''', '''Feats''', and other special notes about your character or of a certain piece of equipment or ability. When using the Charactermancer, the previously mentioned features appears in this section.<br />
<br />
This block can be set up to be <span style="font-family:Pictos;">i</span> [[Compendium|Compendium Compatible]] (where you can add repeating sections for individual items) or as one resizable free-text field to enter whatever you wish in here. You can adjust this block's behavior by going to the [[D&D 5E by Roll20#Settings Page|Settings Page]] of the sheet and going to the '''General Options'''-block to change whether this block uses the Simple or Compendium Compatible layout. <br />
<br />
When adding items to the Compendium Compatible version of this block, you have the <code>Name</code> field, a <code>Source</code>-field where you can choose between (Racial, Class, Feat, Background, or Other) , a <code>Source Type</code>-text field to describe the type, and then the multilined <code>Description</code>-textbox. Clicking on the <span style="font-family:Pictos;">y</span>(gear)-icon in the top right corner of the item will lock/unlock the item's editability. When locked down, a <span style="font-family:Pictos;">w</span>(chat bubble)-icon appears when you mouse over the feature/trait. Clicking on the <span style="font-family:Pictos;">w</span> will share this feature's description in the {{Text Chat}}.<br />
<br />
There presently isn't a means to format the raw text (italicize, bold, font alignment, etc) of the Simple version or in the Description section of either version of the Features & Traits block.<br />
<br />
You can drag-n-drop '''Feats''' from the compendium, even though they can't be selected in the Charactermancer on levelup.<br />
<br />
PC Features and Traits can be called using an ability roll:<br />
<code>%{selected|repeating_traits_$0_output}</code><br />
Simply increase the $0 value to access all Features and Traits listed on the character sheet, $1, $2, $3...<br />
<br />
<p style="clear:both;"></p><br />
<br />
==Bio Page==<br />
[[File:D&D5E-Roll20-BIO-tab.png|right|thumb|250px|The Bio Page of the PC Sheet]]The Bio page, opened by selecting "BIO" from the 4 buttons near the top right of the sheet, is comprised of free-form text fields that can be used to keep track of less "structured" information about your character. You can use this page to describe your character's appearance, keep track of who their allies are and what organizations they've worked for, and on this page is a section to supplement the inventory list, on the front page, with the "Treasure" section, where you can keep track of all the loot you find along your travels.<br />
===Bio Header===<br />
[[File:D&D5E-Roll20-Bio-header.png|550px]]<br /><br />
<br />
The header of the Bio page contains the basic run down of a character's physical appearance.<br />
*'''Character Name:''' This is carried over from every single PC Page and matches the character journal's name<br />
*'''Age:''' The character's current age<br />
*'''Size:''' The size classification for the race type (Medium for most cases)<br />
*'''Height:''' The character's height<br />
*'''Weight:''' The character's weight<br />
*'''Eyes:''' The character's eye color<br />
*'''Skin:''' The character's skin color<br />
*'''Hair:''' The character's hair color/style<br />
<br />
===Character Appearance===<br />
While the Bio Header describes the bare bone physical characteristics of a PC, this field is for fleshing out the visual peculiarities and/or cues of your character. Does you character have a piercing gaze? A stooped posture? Are they fancily dressed or are their clothes moth-eaten? In essence, this field is for everything and anything one would note about the character–from the equipment or garb they wear to how they comport themself.<br />
<br />
===Allies & Organization===<br />
This text field is for listing important or campaign relevant NPCs that the character may have a connection with. It's also for keeping track of faction allegiance. In the case of ''Dungeons & Dragons''' Forgotten Realms world, a PC could be a member of the Harpers or the Emerald Enclave, among other major factions who are all vying for power of the continent.<br />
<br />
===Character Backstory===<br />
This field is for listing your character's pre-campaign history, their relations, and the pertinent places they have been to in the past.<br />
<br />
===Additional Features & Traits===<br />
This text field is a continuation of the [[#.2817.29_Features_.26_Traits | Features & Traits]] section of the Core Page. The section on the Core Page is a good place for commonly utilized features of a character or briefly jotting down an abbreviated list. This field on the Bio page gives you more real estate to fully write down everything you need in whole.<br />
<br />
===Treasure===<br />
This text field is where you can list all the loot you've collected while searching bodies and delving through dungeons. Since much of these effects are transient and are likely to be used, given away, or sold to the highest bidder at the earliest opportunity, this may be preferable place to keep this list of items rather than adding them to the itemized Compendium Compatible Equipment section (if you have that version enabled).<br />
<br />
==Spell Page==<br />
[[File:D&D5E-Roll20-Spells-tab.png|right|thumb|400px|The Spell Page]]The Spell page, opened by selecting the "SPELLS" button from the four buttons near the top right of the sheet, is used to keep track of all of the powerful magics at your character's fingertips.<br />
<br />
===Spell Page Header===<br />
[[File:D&D5E-Roll20-Spells-header.png|550px]]On the Spells page Header you can set the ability modifier that will be used for casting spells. Selecting the Spellcasting Ability block will allow you to select an attribute from a dropdown, and this will be used in all relevant spell rolls. This attribute will be set automatically when you select a spell casting class. The next two blocks, the Save DC and Attack Bonus will be set automatically based on the class that is selected on the Core page.<br />
<br />
===Spellcasting Ability===<br />
The Spellcasting Ability modifier will automatically update, depending on the class you select on the Core page, to the correct ability modifier for your class. If, for some reason, you need to change this value you can click on the modifier listed in this section and it will give you a drop-down list of all available ability modifiers.<br />
<br />
===Spell Save DC & Attack===<br />
The Spell Save DC and Spell Attack Bonus sections cannot be changed manually, but are just a visual output of modifiers that will be happening behind the scenes. The Spell Attack Bonus is the number that will be added to all spell attack rolls, automatically.<br />
<br />
The Spell Save DC refers to the Save DC that enemies will have to beat when they are trying to dodge/resist your incoming spells. Say, Fred the Sorcerer casts Lightning bolt, and his Spell Save DC is 14. Any enemies hit by his attack will have to make a DEX save and try to beat 14. If they manage to beat the attack, then they are only grazed and take half of the damage. If they don't beat 14, then they take the full damage of the attack instead.<br />
<br />
===Spell Levels & Spells Per Day===<br />
The main section of the Spells page lists 10 sections, ranging from 0 to 9, representing the Cantrips (0) and spells level 1 - 9 where the level of the spell is listed in the triangle on the left of each section header. The number in the left square of the header represents the total number of Spell Slots, in other words, the maximum number of times a spell of this level can be cast in between long rests. This number will be set automatically depending on the level of your character, but can be modified by clicking the up or down arrow or just entering a number in the space provided. The number in the right-most box in the headers is the Slots Remaining value that can be used for you to keep track of the number of times you've cast a spell at this level.<br />
<br />
===Adding Spells===<br />
[[File:D&D5E-Roll20-Spells-Icons.png|framed|right]]<br />
When you drag spells from the <span style="font-family:Pictos;">i</span> [[Compendium]] to the sheet, a new spell entry will be added to the Spell Page under the appropriate level header. This will copy over all corresponding information linked to the spell, as well as creating an attack entry in the [[D%26D_5E_by_Roll20#.2811.29_Attacks_.26_Spellcasting|Attacks & Spellcasting]]-block on the "Core" page, if the spell can be used as an attack. The name of the spell will be listed to the left of the entry and to the right are icons for whether the spell is a Ritual (R), requires Concentration (C), and lists whether there is a Verbal (V), Somatic (S), or Material (M). There is also a circle at the far left of the entry that can be toggled to be filled in with red or left empty. This toggle represents spells that are Prepared for the day and are available for a player's convenience to help track this.<br />
<br />
You can manually add spells by selecting the <span style="font-family:Pictos;">&</span> under any of the Spell Level headings. This will present you with a blank template where you can enter all of the information about a spell. By default, the spell card only contains non-attack information about a spell. If the spell IS an attack you can change the "Output" selector from "Spellcard" to "Attack", this will show some additional input fields to fill out the attack information about the spell. Switching this input will also add an attack entry to the [[D%26D_5E_by_Roll20#.2811.29_Attacks_.26_Spellcasting|Attacks & Spellcasting]]-section on the [[#Core Page|Core page]] so this spell attack can also be cast from the main page. All of these sections are linked, so changing information in one place will also change the corresponding information in the other location. To save your edits, click on the gear icon at the upper right of the entry to collapse the spell entry.<br />
<br />
You can edit any spell at any time, by hovering your mouse over the entry to make a <span style="font-family:Pictos;">y</span> icon appear on the left. Clicking on the <span style="font-family:Pictos;">y</span> will roll out the spell once more to be edited.<br />
<br />
==Settings Page==<br />
[[File:D&D5E-by-Roll20-Settings-Page.png|thumb|right|400px|The Settings tab of the sheet, accessed from the '''<span style="font-family:Pictos;">y</span>''' icon ]]<br />
The Settings page, accessed by selecting the <span style="font-family:Pictos;">y</span>(gear) icon from the four buttons near the top right of the sheet, is where you can make changes to some parts of your character sheet that aren't represented on the other pages.<br />
<br />
===Class Options===<br />
In the class options section is where you have access to some important parts of your character, that usually are managed in the background. They are placed here so that, if needed they can be modified as well.<br />
<br />
'''Hit Dice:''' This section will be set automatically depending on the class chosen on the [[#Core Page|Core page]], but can be changed here by selecting the value and choosing a new one from the drop-down menu. This option is used whenever the "Hit Dice" section is used on the Core page.<br />
<br />
'''Carrying Capacity Modifier:''' This modifier allows you to increase the weight that a character can carry before they become encumbered.<br />
<br />
'''Global Magic Attack Modifier:''' This modifier will affect all spell attacks rolled from the sheet.<br />
<br />
'''Magic Caster Level:''' By default, a character's caster level is tethered to their class level. This option allows you to set the caster level manually, so you can have it differ from the character's class level. This will automatically change the Spell Slots Total for each spell level on the [[#Spell Page|Spells page]].<br />
<br />
'''Spell Save DC Mod:''' The Spell Save DC is normally a field you can't edit from the Spell page and is set by the character's class and level. This modifier allows you to alter that value.<br />
<br />
'''Spell Icons:''' This option will allow you to choose to turn off all the Spell Icons (R, C, V, S, & M), show them all, or only display only the ritual and concentration icons.<br />
<br />
'''Halfling Luck:''' Use this checkbox if your character is a Halfling that happens to take advantage of the Halfling Luck race feat. Using this feat will automatically re-roll any 1s rolled for attacks and skills or ability checks/saves.<br />
<br />
'''Arcane Fighter/Rogue:''' These checkboxes can be used to keep track of when your Fighter or Rogue-classed character actually has access to spells.<br />
<br />
===Multiclass Options===<br />
If you are taking advantage of the D&D 5E multiclassing you can keep track of it in this section. Any levels to your character's additional classes must be changed here, and will then be reflected in the header portion of the sheet. Once you've added additional classes in this section, any time you roll Hit Dice from the Core page it will ask you which classes hit dice you wish to use.<br />
<br />
Note: Be sure to not re-include your main class in this section, or your final level calculation will be incorrect.<br />
<br />
===Custom Class Options===<br />
If you are playing a class that is not part of the D&D 5E Compendium, you can input the important class information in this section, and checking the "Use Custom Class" checkbox will replace the main class selection with your custom built class.<br />
<br />
===Spell Slot Modifiers===<br />
This section allows you to manually modify how many spell slots your character has available for each spell level from 1 to 9.<br />
<br />
===Attribute Options===<br />
'''Attribute Modifiers:''' With this section you can manually adjust the individual Attribute Scores for Strength, Dexterity, Constitution, Intelligence, Wisdom, and Charisma.<br />
<br />
'''Initiative Modifier:''' Usually, your initiative modifier is just based off of your DEX modifier, but if you happen to find a magical item that enhances these rolls this is where you will put that bonus. This modifier will be used whenever the [[#.287.29_Armor_Class.2C_Initiative.2C_.26_Speed|Initiative]]-section is rolled on the Core page.<br />
<br />
'''Initiative Style:''' This setting allows you to select whether Initiative will be rolled with Advantage, Disadvantage, or rolled normally with a single d20 (default).<br />
<br />
'''Add DEX Tiebreaker to Initiative:''' If you would like to enable a tie breaker component to Initiative, this checkbox will enable adding your dexterity Attribute Score as a decimal value to your Initiative roll. So if you have a character with a dexterity attribute score of 14, your initiative modifier will change from a 2 to a 2.14.'<br />
<br />
'''Global Armor Class Modifier:''' This setting will modify your armor class and will be taken into account regardless of the equipment the character uses.<br />
<br />
'''Armor Class Tracking:''' There are three options available: The Automatic version that's default to the sheet where it adds 10 + your DEX modifer and then takes any armor equipped into account. A Custom version which expands out a formula upon selection where you can input your own formula for armor tracking, or you can turn Off Armor Tracking entirely. When turned off, you will need to manually adjust the Armor Class field on the Core page.<br />
<br />
===Save Options===<br />
'''Save Modifiers:''' With this section you can manually adjust the individual Save modifiers for Strength, Dexterity, Constitution, Intelligence, Wisdom, and Charisma.<br />
<br />
'''Death Save Modifier:''' A normal death save is usually just a D20 against a dc of 10, but if you're lucky enough to have a bonus to death saves, this is where you will put your bonuses. This modifier will be represented any time a "Death Save" is rolled from the Core page.<br />
<br />
'''Global Saving Throw Modifier:''' If you have an affect that would modify all saving throws, this option makes it easier to adjust your Save modifiers than having to go in and change each one individually. This modifier will be used every time any save is rolled from the sheet.<br />
<br />
===Skill Options===<br />
If your class offers the ability to achieve "Expertise" in a skill, or if you are using a Bard with the "Jack of All Trades" feat, this is where you will make these adjustments. There is also a section to add flat modifiers to any of your skills if your character has an archetype ability like Remarkable Athlete or a feat that adds a flat bonus to a skill. You can add expertise to any skill by clicking the value next to it and choosing "Expertise" from the drop-down menu. If your Bard has the Jack of All Trades feat, you can check the checkbox at the bottom of this section and it will automatically give half of your character's proficiency points to any skill check that doesn't have full proficiency.<br />
<br />
'''Passive Perception Modifier:''' This option will add a bonus to a character's Passive Perception which is not something you can change directly from the Core page of the sheet.<br />
<br />
===General Options===<br />
The General Options section has some important options that deal more with how the sheet works, rather than actual character creation. Most importantly, the NPC checkbox at the top, which will change the sheet to be the NPC version which is shaped to more easily track an NPC's information.<br />
<br />
'''Roll Queries - Always/Toggle/Query/Never Roll Advantage:''' This option will change how advantage is rolled for all attacks. It defaults to always roll advantage, which means that every time an attack is rolled it will roll twice and present the outcome of both rolls. This is useful for both advantage and disadvantage, otherwise you can just choose either the left or the right to be the default roll. Toggle adds a set of buttons at the top of the sheet to manually switch your advantage options between rolls. If Query is chosen, every time a roll is made it will ask you whether or not it's advantage. If Never is chosen, then it will always roll just a single dice per attack roll.<br />
<br />
'''Whisper Rolls to GM:''' Like above, you have the option to Never/Toggle/Query/Always whisper rolls to the GM. When this option is enabled, the attack roll will only be whispered to the GM and not made public.<br />
<br />
'''Auto Damage Roll:''' By default, damage rolls will not be rolled automatically, but only when you click the attack in the chat window. This is useful because you can choose to only roll damage when an attack hits. Using this option you can make the character always roll damage with every attack.<br />
<br />
'''Core Die Roll:''' You can change the core die (by default it is 1d20) to something else entirely here.<br />
<br />
'''Proficiency Bonus:''' By default, the character's Proficiency Bonus is calculated by class level. This setting allows you choose to calculate this bonus via By Level (the default), via a Proficiency Die as described in the Dungeon Master's Guide, or a Custom calculation which rolls out a field to enter a roll formula for the bonus.<br />
<br />
'''Global Save/Skill/Attack/Damage Modifier Field:''' This series of checkboxes will add new entries to the Saving Throws, Tools Proficiencies & Custom Skills, and Attacks & Spellcasting blocks respectively to add global modifiers (like if a character is under the effects of a Bless or Guidance spell). Each entry will have a Global label in grey at the bottom of its entry and a field to enter the modifier bonus. If you include a word in brackets with the bonus formula (ex. "1d4[Bless]"), the word enclosed in the brackets will appear when you mouse over a roll to see it's formula.<br />
<br />
'''Add Character Name to Templates:''' This option allows you to turn this on or off. When it is on, the character's name is listed in the roll template when rolls are made from the sheet. If the character sheet in question is for an NPC, you will likely want to have this off so the rolls don't accidentally show your hand of what sort of monster your party is facing. This setting is off by default.<br />
<br />
'''Auto Level Calculations:''' This option allows you to turn this on or off. When it is on, adjusting the character's class level will automatically update the character's proficiency bonus, Hit Dice, and spell Slot totals (if the class is a spellcaster).<br />
<br />
'''Encumbrance:''' This option dictates how encumbrance is handled on the Equipment block of the Core page. This requires your Inventory to be set to "Compendium Compatible" to automatically calculate and track the weight of your character's backpack if you enter the weight values for any of the items in your Equipment list. When your character becomes encumbered, and depending on its severity, the words ENCUMBERED, HEAVILY ENCUMBERED, or IMMOBILE will display in red underneath the TOTAL WEIGHT value. This setting has three options: Simple Encumbrance Rules, Variant Encumbrance Rules, or not follow Encumbrance rules at all by toggling it off from this.<br />
<br />
'''Inventory:''' With this option allows you to either have your Equipment block be "Compendium Compatible" or "Simple". The Simple version of the Equipment block will give you single text field to log your inventory. The Compendium Compatible version tracks weight, quantity, and attack options in an itemized list for every equipment item you add to the block.<br />
<br />
'''Features & Traits:''' This option can set the Features & Traits block to be either a single text field or a repeated section that will be Compendium Compatible to list traits and features in an itemized list.<br />
<br />
'''Proficiencies & Languages:''' This option can set the Proficiences & Languages block to be either a single text field or a repeated section that will be Compendium Compatible to list traits and features in an itemized list.<br />
<br />
'''Ammo Tracking (API Required):''' When using the 5th Edition OGL Companion API Script in your game (Pro Subscriber feature), you can set attacks to weapons using ammunition to automatically subtract from their tally in their Resource block. So if your character is equipped with a bow, rolling its attack will automatically remove an arrow from its Resource block.<br />
<br />
===Transition Options(outdated)===<br />
{{mbox | text = This feature doesn't seem to exist on the sheet any longer, so the info in this section is outdated}}<br />
<br />
If your campaign previously used the [https://wiki.roll20.net/DnD5e_Character_Sheet#Intro Community Contributed] or [https://wiki.roll20.net/index.php?title=DnD5e_Shaped_Character_Sheet&oldid=11112#General_Information Shaped Legacy] 5th Edition Character Sheets and you are swapping over to this one, we have an automated conversion tool that will clear or merge elements left over from those two sheets. This procedure can only be done ''once'' and can not be undone. It is recommended that you make a copy of your campaign first before attempting a sheet transition.<br />
<br />
There is also a checkbox that hides this feature entirely from the sheet. If you hide this by mistake, you can gain access to it again by creating a new character journal.<br />
<br />
=The NPC Sheet=<br />
''See Also:'' '''[[D&D5E by Roll20 NPC Attributes]]'''<br />
<br />
One of the most useful parts of the D&D 5E by Roll20 Character Sheet is that it contains both a PC sheet ''AND'' an NPC sheet. An NPC doesn't normally require the depth a PC sheet needs, so the NPC sheet is a much more slimmed down character sheet that doesn't require multiple pages like its PC counterpart. You can access this version of the sheet by going to the Settings Page, by clicking the gear icon near the top right of the sheet, and then checking the NPC checkbox. This will switch the sheet to the NPC version. You can switch back at any time by unchecking the NPC option under General Options on the new page.<br />
<br />
==NPC Options==<br />
[[File:5E_OGL_Sheet_NPC_Options.png|right|thumb|250px|The NPC Options Section]]This is the area where all of the NPC's stats will be entered, it covers everything from the NPC's name, to how strong or quick or smart it is, to what languages it speaks. Most of the fields in this section are just text fields used to keep track of information about the NPC. All of the information entered in these fields will be visible in the stat block once the NPC options are hidden. <br />
<br />
<br />
Any text that appears in light grey is placeholder text. It's there to offer you an example of what the content would be for any given field. <br />
<br />
By default, no skill or ability checks will show up in the NPC's stat block. Once you've added a value to the corresponding skill or ability save, they will appear. If for some reason the NPC will have to make a check with a skill or ability it does not have any bonus in, you can enter a 0 as the modifier for that check and it will add it to the list in the stat block below.<br />
<br />
The XP of an NPC auto-calculates based on its given challenge rating.<br />
<br />
If the NPC is a spellcaster, you can check the checkbox beside '''SPELLCASTING NPC''' and this will add a spell list section that utilizes the spell list and its functionality from the PC version of the sheet.<br />
<br />
At default, you can add Traits and Actions in their respective places after the Challenge Rating and XP area of the Stat Block. For Reactions and Legendary Actions, you need to enable them from the NPC Options section. For Reactions, check off the '''HAS REACTIONS''' checkbox. This will add a new sections to the Stat Block for you to add Reactions to. If an NPC is a monster with Legendary Actions then you must enter the number of actions that monster has access to each turn in the '''LEGENDARY ACTIONS:''' field. Once you add a number here, an additional section will appear in the stat block below, where you can add the specific legendary actions that the monster is able to do.<br />
<br />
The NPC sheet supports Compendium drag & drop. If you want to add a new monster to your game just drag the monster from the <span style="font-family:Pictos;">i</span> [[Compendium]]-tab of the [[Sidebar]] and drop it to anywhere on the Tabletop. This will automatically create a new journal entry named the same as the Compendium entry and will copy all of the information on that compendium page directly into the new sheet. If you have purchased any of the Compendium expansions that expands on the available NPCs like the Monster Manual or Volo's Guide to Monster, a token of that NPC will be added to the Tabletop that will have its stats automatically set and linked to the new journal entry.<br />
<br />
{{mbox | text = '''Note:''' If you already have a journal entry in your {{journal}}-tab with the exact same name as the <span style="font-family:Pictos;">i</span> [[Compendium]] entry, the drag and drop will not work as this automation will stop to prevent overwriting existing content the user has already created. If a drag and drop of an NPC Compendium page does not create a journal entry, run a search for that NPC's name in your Journal to see if an entry already exists. If you do not want to delete the older entry, renaming it will allow the drag and drop to work as expected.}}<br />
<br />
===General Options===<br />
Within the NPC Options section, directly below the Legendary Actions field, is the General Options that are featured on the PC Sheet: NPC checkbox, WHISPER ROLLS TO GM, and the AUTO DAMAGE ROLL options. <br />
<br />
*NPC checkbox<br />
*WHISPER ROLLS TO GM<br />
*AUTO DAMAGE ROLL<br />
*NPC NAME IN ROLLS<br />
*ADD DEX TO TIEBREAKER TO INITIATIVE<br />
<br />
Unchecking the NPC checkbox from here will revert the sheet back to the PC Sheet.<br />
<br />
===Hiding NPC Options===<br />
Once all of the desired information has been entered, you can click the <span style="font-family:Pictos;">y</span>(gear) icon at the top right to hide this section. This leaves behind just the NPC's stat block where you can make all of your rolls from. You can re-open this section to edit the information at any time by clicking on the <span style="font-family:Pictos;">y</span> icon again. It's in the same location regardless if you're looking at NPC Options or the NPC stat block.<br />
<br />
==The NPC Stat Block==<br />
[[File:5E OGL Sheet NPC v2.png|right|thumb|250px|An NPC stat block for a griffon]]Following NPC Options is the NPC Stat Block that is built off of what you input in the NPC Options section. This area may look very similar to a stat block you may find in a monster bestiary or published adventure.<br />
<br />
<br />
Any section of the stat block that has a corresponding roll will have click-able text. For example, if the NPC has to make a CON check, you can click the CON attribute to roll a CON check with all of the required modifiers automatically included. If you added a value to one of the skill modifier fields then that skill will show up in the NPC's "Saving Throws" list where you can click it to make a saving throw roll using that skill's modifier.<br />
<br />
The first section of the Stat Block mirrors all the information you added in the NPC Options section. This content is meant exclusively for rolling and can not be edited directly. You will need to change them from the NPC Options section.<br />
<br />
===Traits===<br />
Traits are pieces of information about an NPC that isn't covered by the NPC options section. These are entered directly onto the NPC's stat block. If you click the "<span style="font-family:Pictos;">&</span>" button that appears right below the "Senses/Languages/Challenge Rating" section it will add a blank entry where you can add a single trait for that NPC. Each Trait Entry features a bold title field which is then followed by a larger text box for the description of the trait. You can add any number of Traits for any NPC.<br />
<br />
===Actions===<br />
NPC actions can be used for any number of things. Each entry initially offers an Action Name field as well as a large text field for the Action description. The checkbox for ATTACK, once checked, adds more structured data fields needed for an attack roll (Type, Range/Reach, To Hit bonus, Target, Damage Roll, and Damage Type). To add a new entry you will select the <span style="font-family:Pictos;">&</span> button that appears below the Actions section. Once all of this is complete you can click the <span style="font-family:Pictos;">y</span>(gear) icon at the top of this entry to hide the input fields, leaving just the action text. You can show this information, or roll the attack, in the chat box by clicking the text for the action. If you need to make further modifications to any action you can hover over the row you wish to edit, then click on the <span style="font-family:Pictos;">y</span>(gear) icon again. This will show all of the action information input fields again. You can add any number of Actions for any NPC.<br />
<br />
===Bonus Actions===<br />
NPC bonus actions are typically not listed on the sheet, and are usually referenced in the Traits section. However, if a player wishes to use this section, it is available if the 'Bonus Action' checkbox is selected. The fields work the same as the Actions section.<br />
<br />
===Reactions===<br />
Once enabled from the NPC Options section, a new heading labeled "Reactions" and its relevant section is added to the stat block that allows you to add Reactions. These entries operate just like Traits.<br />
<br />
===Spells===<br />
Once enabled from the NPC Options section, a new heading labeled "Spells" and its relevant section is added to the stat block that allows you to add Spells. These entries will operate identically to how Spells are added and handled on the PC Sheet with the one noted exception that there is only a single column of spell entries. You can drag spells from the Compendium to add spell entries just like you would with the PC's Spell sheet. Any and all spells added to the character sheet are shared between the NPC and the PC versions.<br />
<br />
===Legendary Actions===<br />
If a number value is added to the LEGENDARY ACTIONS field in the NPC Options section, the Legendary Actions heading and section is added at the very bottom of the stat block and lists some verbiage on how many actions are available to be used on a given turn. This number is dictated by what you entered in the NPC Options. These entries operate the same way as Traits.<br />
<br />
==Rolling for Initiative for NPCs==<br />
There are two ways to roll for Initiative on the NPC sheet. You can click on the NPC's Name to roll for Initiative or you can roll from the die icon labeled INIT that is listed to the right of the Armor Class and Hit Points section of the NPC sheet, towards the top. If you have the Turn Tracker tool open, having the NPC token selected while rolling Initiative will automatically add the NPC and its initiative roll to the tracker. Creatures on the GM layer that are added to the tracker in this fashion will have their entries hidden from the players.<br />
<br />
<br />
You can also create a global Macro that will pop up as a Token Action button in the upper left hand corner of the tabletop every time a token is selected. This will allow you to roll without looking at the NPC sheet at all. The macro formula should look just like this:<br />
<br />
<code>%{selected|npc_init}</code><br />
<br />
=Advanced Use=<br />
<br />
===Custom Skills and Stats===<br />
You can set up any number of custom skills or rolls from the [[#Tool Proficiencies|Tool Proficiencies]] section just underneath the skill section on the Core tab. [[#Class & Other Resources|The Resources]] section is also useful for tracking custom stats to your campaign, game setting, or home-brew rules. There are also various options available from the Settings page to modify attributes, skills, saves, spells, and more.<br />
<br />
===Target Roll Buttons===<br />
A useful way for GMs and Players to reference their abilities is by dynamically setting up a handful of macros that can be used on a token linked to a character, rather than having to roll directly from the sheet. To do this, you'll set up a global macro from the {{Collections}}-tab. You can also write these directly in the {{Text Chat}}.<br />
<br />
In the examples, the <code>selected</code> part can be replaced with <code>target</code>, a character's name, or it's character ID.<br />
<br />
Here are some examples:<br />
<br />
'''PC'''<br />
* Attributes: <code>%{selected|strength}</code>, <code>%{selected|strength_save}</code> | Will roll the Strength Check and Strength Save for the selected [[token]](if the [[Link Token|token is linked to a sheet]])<br />
* <code>%{selected|acrobatics}</code><br />
* <code>%{selected|initiative}</code><br />
* <code>%{selected|death_save}</code><br />
* <code>%{selected|hit_dice}</code><br />
<br />
'''NPC'''<br />
* <code>%{selected|npc_init}</code><br />
* <code>%{selected|npc_str}</code><br />
* <code>%{selected|npc_stealth}</code><br />
* <code>%{selected|npc_hpformula}</code><br />
====Dynamic References to Repeating Sections====<br />
The example we'll be using today is setting up the 1st NPC action:<br />
<code>%{selected|repeating_npcaction_$0_npc_action}</code><br />
Now whenever you use this macro it will roll the first NPC action of whichever NPC token you have selected. You can set up a roll for each action by incrementing the 0 by 1 for each action you wish to add (I.E. <code>$1</code>, <code>$2</code>, <code>$3</code>). Here is a list of important repeating section rolls and their formulas:<br />
<br />
* Player Attack/Spell Attack <code>%{selected|repeating_attack_$0_attack}</code><br />
* Player Attack/Spell Damage <code>%{selected|repeating_attack_$0_attack_dmg}</code><br />
* Player Attack/Spell Critical Damage <code>%{selected|repeating_attack_$0_attack_crit}</code><br />
* Player Global DMG mod <code>%{selected|repeating_damagemod_$0_global_save}</code><br />
** Attr names: <code>global_damage_name</code>, <code>global_damage_damage</code>, <code>global_damage_critical_damage</code>, <code>global_damage_type</code><br />
* Proficiencies <code>%{selected|repeating_proficiencies_$0_output}</code><br />
* Tool/Custom Skill <code>%{selected|repeating_tool_$0_tool}</code><br />
* Traits/Feats: <code>%{selected|repeating_traits_$0_output}</code><br />
<br />
* Spellbook Cantrip <code>%{selected|repeating_spell-cantrip_$0_spell}</code><br />
* Spellbook Level 1 <code>%{selected|repeating_spell-1_$0_spell}</code><br />
* Spellbook Level 2 <code>%{selected|repeating_spell-2_$0_spell}</code><br />
* Spellbook Level 3 <code>%{selected|repeating_spell-3_$0_spell}</code><br />
* Spellbook Level 4 <code>%{selected|repeating_spell-4_$0_spell}</code><br />
* Spellbook Level 5 <code>%{selected|repeating_spell-5_$0_spell}</code><br />
* Spellbook Level 6 <code>%{selected|repeating_spell-6_$0_spell}</code><br />
* Spellbook Level 7 <code>%{selected|repeating_spell-7_$0_spell}</code><br />
* Spellbook Level 8 <code>%{selected|repeating_spell-8_$0_spell}</code><br />
* Spellbook Level 9 <code>%{selected|repeating_spell-9_$0_spell}</code><br />
<br />
'''NPC'''<br />
* NPC Traits/Abilities<code>%{selected|repeating_npctraits_$0_npc_roll_output}</code><br />
* NPC Actions/Attacks<code>%{selected|repeating_npcaction_$0_npc_action}</code><br />
* NPC Attack Damage<code>%{selected|repeating_npcaction_$0_npc_dmg}</code><br />
* NPC Attack Critical Damage<code>%{selected|repeating_npcaction_$0_npc_crit}</code><br />
* NPC Bonus Actions<code>%{selected|repeating_npcbonusaction_$0_npc_action}</code><br />
* NPC Legendary Actions<code>%{selected|repeating_npcaction-l_$0_npc_action}</code><br />
* NPC Mythic Actions<code>%{selected|repeating_npcaction-m_$0_npc_action}</code><br />
* NPC Spells<code>%{selected|repeating_spell-npc_$0_spell}</code><br />
<br />
===Directly Referencing Attributes===<br />
You can discover the name of most of the attributes in the sheet by hovering over them. After a couple of seconds a title will pop up and tell you how to referencing them. You can call attributes in an Ability Rolls by using <code>@{attributename}</code>. If you want to directly reference it in a roll that isn't saved on the sheet, you need to specify the character's name, or use either the <code>selected</code> or <code>target</code> key works.<br />
<br />
'''Examples:'''<br />
* <code>/em attempts to grapple and gets [[1d20+@{strength_mod}]]</code> custom [[Journal#Attributes_.26_Abilities_Tab|Ability call]], saved in the "attributes and abilities" tab of the character sheet.<br />
* <code>/r 1d20+@{Alice|strength_mod}+@{Alice|pb}</code> macro that calls a specific character<br />
* <code>/em have @{selected|hp} out of @{selected|hp|max} left.</code> macro that uses stats from a token(token must be selected before rolling)<br />
* <code>The Enemy's AC is @{target|npc_ac}</code> macro prompt the user to select a target token on the map, and uses it's stats.<br />
<br><br />
<br />
See [[Macros#Attribute_Macros]] for further general details/examples on the syntax.<br />
====PC====<br />
Here are a list of some of the more important stats:<br /><br />
<br />
'''Attributes/Saves:'''<br />
<br />
* Str: <code>strength, strength_mod, strength_save_bonus</code><br /><br />
* Dex: <code>dexterity, dexterity_mod, dexterity_save_bonus</code><br /><br />
* Con: <code>constitution, constitution_mod, constitution_save_bonus</code><br /><br />
* Int: <code>intelligence, intelligence_mod, intelligence_save_bonus</code><br /><br />
* Wis: <code>wisdom, wisdom_mod, wisdom_save_bonus</code><br /><br />
* Cha: <code>charisma, charisma_mod, charisma_save_bonus</code><br />
<br><br />
'''Skills:'''<br />
<br />
<code>athletics_bonus<br /><br />
acrobatics_bonus<br /><br />
animal_handling_bonus<br /><br />
arcana_bonus<br /><br />
deception_bonus<br /><br />
history_bonus<br /><br />
insight_bonus<br /><br />
intimidation_bonus<br /><br />
investigation_bonus<br /><br />
medicine_bonus<br /><br />
nature_bonus<br /><br />
perception_bonus, passive_wisdom<br /><br />
performance_bonus<br /><br />
persuasion_bonus<br /><br />
religion_bonus<br /><br />
sleight_of_hand_bonus<br /><br />
stealth_bonus<br /><br />
survival_bonus<br /><br />
</code><br />
<br />
'''AC, Proficiency, HD etc'''<br />
<br />
<code>pb</code>(Proficiency Bonus)<br><br />
<code>inspiration</code><br><br />
<code>ac<br /><br />
initiative_bonus<br /><br />
speed<br /><br />
hp, hp|max, hp_temp<br /><br />
hit_dice, hit_dice|max, hitdietype<br /><br />
weighttotal<br /><br />
</code><br />
<br />
'''Spells'''<br />
<br />
<code>spell_save_dc, spell_attack_bonus<br /><br />
lvl1_slots_total, lvl1_slots_expended<br /><br />
lvl2_slots_total, lvl2_slots_expended<br /><br />
lvl3_slots_total, lvl3_slots_expended<br /><br />
lvl4_slots_total, lvl4_slots_expended<br /><br />
lvl5_slots_total, lvl5_slots_expended<br /><br />
lvl6_slots_total, lvl6_slots_expended<br /><br />
lvl7_slots_total, lvl7_slots_expended<br /><br />
lvl8_slots_total, lvl8_slots_expended<br /><br />
lvl9_slots_total, lvl9_slots_expended<br /><br />
</code><br />
<br />
Spells, repeating sections:<br><br />
<code>repeating_spell-cantrip<br><br />
repeating_spell-1<br><br />
repeating_spell-2<br><br />
repeating_spell-3<br><br />
repeating_spell-4<br><br />
repeating_spell-5<br><br />
repeating_spell-6<br><br />
repeating_spell-7<br><br />
repeating_spell-8<br><br />
repeating_spell-9</code><br> <br />
<br />
Cantrip stats(most should also work for lvl.1-lvl.9):<br><br><br />
Full statname is spell level + (rowID or row number) + attribute name, e.g. <code>repeating_spell-1_$0_spellname</code> is the spell name of your first Lvl 1 spell, <code>repeating_spell-4_$1_spelldescription</code> is the description of your second lvl.4 spell.<br />
<br />
<code>spellname<br><br />
spellrange, spellcastingtime, spelltarget, spellduration<br><br />
spellschool<br><br />
spellritual<br><br />
spellconcentration<br><br />
spellcomp_v, spellcomp_s, spellcomp_m<br><br />
spellcomp_materials<br><br />
spell_ability<br><br />
spelloutput<br><br />
spellattack<br><br />
spelldamage, spelldamagetype, spelldamage2, spelldamagetype2<br><br />
spellhealing<br><br />
spelldmgmod, spell_damage_progression<br><br />
spellsave, spellsavesuccess<br><br />
spelldescription<br><br />
spellclass, spellsource</code><br />
<br />
'''Items'''<br><br />
<code>cp sp ep gp pp</code><br><br />
(copper pieces, silver, gold, electrum, platinum)<br />
<br />
<code>repeating_inventory_$#_itemcount<br><br />
repeating_inventory_$#_itemname<br><br />
repeating_inventory_$#_itemweight<br><br />
repeating_inventory_$#_equipped<br><br />
repeating_inventory_$#_useasresource<br><br />
repeating_inventory_$#_hasattack<br><br />
repeating_inventory_$#_itemproperties<br><br />
repeating_inventory_$#_itemmodifiers<br><br />
repeating_inventory_$#_itemcontent</code><br><br />
<br />
* <code>equipped</code>, <code>useasresource</code>, <code>hasattack</code> are checkboxes, with value 1 if checked.<br />
* <code>itemmodifiers</code> is for of item changes any stats, like <code>AC +2</code> adding +2 to AC when equpped.<br />
* <code>itemcontent</code> is the item description<br />
<br><br />
'''The class_resource and the other_resource'''<br><br />
<br />
<code>class_resource</code> and <code>other_resource</code> are static resources. That is to say, you need to keep in mind that they are NOT a part of the repeating section, even though it definitely looks that way on the character sheet.<br><br />
<br />
You use these to access them<br />
<br />
<code>class_resource</code><br><br />
<code>class_resource_max</code><br><br />
<code>class_resource_name</code><br><br />
<code>other_resource</code><br><br />
<code>other_resource_max</code><br><br />
<code>other_resource_name</code><br><br />
<br />
'''The repeating resources'''<br><br />
<br />
Any resources that appear beneath the "class resource" and the "other resource" are a part of the "repeating resources" section. This section is known for being confusing for beginners, so it deserves a bit of clarification.<br />
<br />
First, keep in mind that this is one section (not two sections, as people often think), and that "repeating_resource" is its section prefix.<br />
<br />
Second, keep in mind that you need to skip past the row with the "class resource" when you're figuring out the address of the row that you want to refer to. So basically, if you want to refer to the row that is directly below the row with the "class_resource", then you would add "_$0" (to form "repeating_resource_$0"). And then the next row after that is "_$1", and so on.<br />
<br />
Third, keep in mind that if you add "_resource_left" (to form "repeating_resource_$0_resource_left"), then you are specifying that you are talking about the CURRENT VALUE of the leftmost resource in that row. And if you add "_resource_left_max", then you are specifying that you are talking about the MAX VALUE of the leftmost resource in that row.<br />
<br />
Here is a complete list of all the fields that you can access in the "repeating_resource" section. Just replace the "#" character with which row you want to access.<br />
<br />
<code>repeating_resource_$#_resource_left</code><br><br />
<code>repeating_resource_$#_resource_left_max</code><br><br />
<code>repeating_resource_$#_resource_left_name</code><br><br />
<code>repeating_resource_$#_resource_right</code><br><br />
<code>repeating_resource_$#_resource_right_max</code><br><br />
<code>repeating_resource_$#_resource_right_name</code><br><br><br />
<br />
<br />
'''Features/Class Traits'''<br />
<br />
<code>repeating_traits_$0_output<br><br />
repeating_traits_$#_name<br><br />
repeating_traits_$#_source<br><br />
repeating_traits_$#_source_type<br><br />
repeating_traits_$#_description<br><br />
</code><br />
<br />
'''Other/Settings:'''<br />
<br />
<br><br />
<code><nowiki>wtype</nowiki></code> (whisper type, can have one of these values:)<br />
* <code><nowiki></nowiki></code> (empty for never whisper)<br />
* <code><nowiki>@{whispertoggle}</nowiki></code> (show the buttons on sheet that can toggle between options)<br />
* <code><nowiki>?{Whisper?|Public Roll,|Whisper Roll,/w gm }</nowiki></code><br />
* <code><nowiki>/w gm</nowiki></code> (always whisper)<br />
<br />
<br />
'''Global modifiers'''<br />
<br />
* <code>repeating_savemod_$0_global_save_roll</code><br />
* <code>repeating_skillmod_$0_global_skill_roll</code><br />
* <code>repeating_tohitmod_$0_global_attack_roll</code><br />
* <code>repeating_damagemod_$0_global_damage_damage</code><br />
<br />
====NPC====<br />
Some stats are the same as for PCs<br />
<br />
<code>npc_name<br><br />
npc_ac<br><br />
hp, hp|max<br><br />
npc_speed<br><br />
npc_challenge<br><br />
npc_xp</code><br />
<br />
Attributes: <code>strength_base, strength_mod</code> (same as PCs)<br />
Saves:<br />
<br />
<code>npc_str_save_base</code>,<code>npc_dex_save_base</code>, <code>npc_con_save_base</code>,<code>npc_int_save_base</code>,<code>npc_wis_save_base</code><code>npc_cha_save_base</code><br />
Skill bonus:<code>npc_acrobatics_base</code>, <code>npc_animal_handling_base</code> etc.<br />
<br />
Damage/Conditions stuff:<br />
<br />
<code>npc_vulnerabilities<br><br />
npc_resistances<br><br />
npc_immunities<br><br />
npc_condition_immunities</code><br />
<br />
Spells:<br />
<br />
<code>npcspellcastingflag</code> (set to "1" if caster, empty otherwise) <br />
<code>spellcasting_ability</code><br />
<code>globalmagicmod </code> (global magic attack modifier)<br />
<code>caster_level</code><br />
<code>spell_dc_mod</code> (spell save DC mod)<br />
<br />
Spells are identical to PC section<br />
<br />
Other:<br />
whisper is same as PCs<br />
<br />
<code>npc_name_flag</code> (show/hide npc name in rolls, value is either <code><nowiki>{{name=@{npc_name}}}</nowiki></code> or <code>0</code>)<br />
<br />
<br />
<sup>Note: anything with the Suffix of <code>|max</code> requires some form of Prefix, such as <code>selected|</code> making the call for such a thing look something along the lines of <code>@{selected|hp|max}</code>. The <code>|max</code> Suffix specifically calls the box on the right of the selected Attribute's Line, for example, you could fill in the Weight Total's 2nd Box with <code>@{strength}*15</code> & whenever you call <code>@{selected|weighttotal|max}</code> it will tell you your 5e standard Maximum Carry Capacity for your current Strength Score.<br />
<br />
===Custom AC Items===<br />
You can add pieces to your inventory and manually give them AC or magic bonuses that will figure into their calculations automatically. Inside the item options is a section for "MODS:". Add <code>Ac +1</code> to add an armor class bonus.<br />
<br />
===Roll Templates===<br />
''Main Article:'' '''[[D&D 5e by Roll20 Roll Templates]]'''<br />
<br />
The '''D&D5E by Roll20''' Character Sheet also includes a series of [[Roll Templates]] that you can use to dress up your own custom macros. Roll Templates provide additional layout and styling options for the display of roll results.<br />
<br />
{{ex}}<br />
[[File:5e-rolltemplate-ex1-2021.png|200px|right|none]]<br />
Rolls stealth for selected npc token, using it's stealth proficiency.<br />
<code><nowiki>/w gm &{template:npcatk} {{attack=1}} {{name=Shadow}} {{rname=Shadow Stealth}} {{rnamec=Hide}} {{r1=[[@{selected|d20}+@{selected|npc_stealth} + 6]]}} {{always=1}} {{r2=[[@{selected|d20}+@{selected|npc_stealth} + 6]]}} {{description=While in dim light or darkness, the shadow can take the Hide action as a bonus action. Its stealth bonus is **also** improved to +6 }}</nowiki></code><br />
<br />
===Magic Missile Spell===<br />
{| role="presentation" class="wikitable mw-collapsible mw-collapsed" style="float:right; margin-left: 10px;margin-right: 60px;"<br />
| Image of the Spell's settings<br />
|-<br />
| [[File:Magic-Missile-5E-2020.png|right|frame|The Magic Missile Spell]]<br />
|}<br />
<br />
RAW, Magic Missile is rolled once, and the single roll is then used for each hit. So by default the spell rolls <code>1d4+1</code>. (See [[Talk:D&D 5E by Roll20#Old Magic Missile Discussion]] for more info.)<br />
<br />
You can modify the spell to instead roll 3d4+3 at first level, and then in the ''HIGHER LVL CAST DAMAGE'' section, set it to <code>1d4+1</code>.<br />
<br />
To automatically use higher-level spell slots with Magic Missile, you have to write a 0 into the ''HIGHER LVL CAST DAMAGE'' section of the spell and select any die. It will show the box for selecting higher-level spell slots when launching Magic Missile, but since it multiplies the higher-level damage cast by 0, the added roll doesn't show up in the chat, making it roll a single die for every missile while using any level spell slot.<br />
<br />
=API=<br />
{{pro only|section}}<br />
[[API:Introduction|API Scripts]] allow for greater customization and functionality to how Roll20 operates beyond what it can do at default. This section will list some info on using various APIs that interact with the character sheet.<br />
<br />
Example of APIs from the One-Click Install menu, that designed to be used with the '''D&D 5E by Roll20''' sheet:<br />
* '''5E BattleMaster'''<br />
* '''5E Resting in Style'''<br />
* '''CashMaster'''<br />
* '''Concentration'''<br />
* '''[[Script:It's a Trap|It's a Trap! -- D&D 5E Generic]] (should detect automatically what sheet is used)<br />
** {{repo|Roll20/roll20-api-scripts/tree/master/ItsATrap_theme_5E_Generic#readme readme}}<br />
* '''ShortRest'''<br />
* '''SpellMaster'''<br />
* '''WildShape'''<br />
<br />
A good number of the more general APIs have built in settings for configuring them for usage with the 5E sheet, such as '''GroupInitiative''', '''GroupCheck''', '''Experience Tracker''', '''[[PowerCards]]''', '''[[ScriptCards]]'''<br />
<br />
* '''[[GroupCheck]]:''' <code>!group-check-config --import 5E-OGL</code> will configure the API for use with this sheet<br />
* '''[[GroupInit|GroupInitiative]]:''' before use, API need to be configured for the sheet, either through the menu preset, or using the command: <code>!group-init --add-group --Bare </code><br />
* '''CombatMaster:''' is by default configured with conditions for D&D 5E<br />
* '''[[ChatSetAttr]]:''' API that can create, edit, & delete stats on sheets. Example: [[Script:ChatSetAttr#Add_new_thing_to_Repeating_Section|Adding a new magic item to a sheet]], with one chat command <br />
* '''[[Script:Ammo]]''' can be used for updating ammo & spellslots when used<br />
<br />
==Utilizing the ''5th Edition OGL by Roll20 Companion'' API Script==<br />
'''{{repo|Roll20/roll20-api-scripts/tree/master/5th%20Edition%20OGL%20by%20Roll20%20Companion 5th Edition OGL Companion}}'''is an official companion script for the "D&D 5E by Roll20" character sheet. The Companion currently supports Ammo Tracking, Automatic NPC Tokens, Automatic Death Save Tracking, and Automatic Spell Slot Tracking. <br />
<br />
{{mbox | text = Installing & creating [[API]] Scripts is a {{Pro}} feature. In order to be able to access these advanced scripts, the [[GM]] of the campaign must be a [[Pro]] subscriber and enable it for their campaign.}}<br />
<br />
<br />
'''''How to Add the API Script to your Game'''''<br />
<br />
If you have a PRO account, you can install the API script by going to your game's Campaign Page and clicking on the '''Settings''' button, and then choosing '''API Scripts'''. This brings you to the API Scripts page for your current game. The Companion Script is part of the One-Click Community API Installation options. Under the Script Library tab, there is a drop down menu that lists all the available community created scripts. Scroll down till you find the '''System Toolbox''' category and select the "5th Edition OGL by Roll20 Companion" script. The version number, the script's author, and a brief description of what the script does will appear right below the drop down menu once it is selected. Below that, click on the blue "Add Script" button to add the script to your game.<br />
<br />
<br />
'''''List of API commands for the 5th Edition OGL Companion API Script'''''<br />
* <code>!5ehelp</code> - Gives a list of the script's API commands in the chat tab.<br />
* <code>!5estatus</code> - Lists the current status of the script's features in the chat tab.<br />
* <code>!ammotracking on/off/quiet</code> - Automatically expends linked resource when attack is made<br />
* <code>!autonpctoken on/off</code> - Automatically generates a NPC token on the GM's screen based on the default token when an NPC's health calculation is rolled<br />
* <code>!deathsavetracking on/off/quiet</code> - Automatically ticks off successes and failures when death saves are rolled, clearing on death, stabilization, or hp recovery<br />
* <code>!longrest <character name></code> - This will add Hit Dice recover and if spelltracking is on, this command will reset all of the character's spell slots to unspent.<br />
* <code>!npchp <character name></code> - Rolls NPC hit point totals using their formula and updates the token bar. If no character name is provided it will roll the selected tokens.<br />
* <code>!spelltracking on/off/quiet</code> - Automatically expends spell charges as cast, factoring in higher level casting, and spells marked as Rituals will not spend a spell slot.<br />
<br />
<br />
Options:<br />
* ''on'' - Toggles the functionality on (default)<br />
* ''off'' - Disables the functionality<br />
* ''quiet'' - Maintains functionality while preventing results from being output to the chat.<br />
<br />
<br />
===Automatic Ammunition Tracking===<br />
''Main Article:'' '''[[D&D 5E by Roll20: How to setup Ammunition and Resource tracker]]'''<br />
<br />
Automatic Ammunition Track is a feature that requires the above Companion API Script. Once installed, follow these instructions to enable automatic ammunition tracking in your game:<br />
<br />
This example sets up a Longbow with a quiver of Arrows to track.<br />
# On the Settings (Gear Icon) tab of a character sheet, under GENERAL OPTIONS, make sure that the INVENTORY option is set to "Compendium Compatible" and not "Simple".<br />
# While still under GENERAL OPTIONS, set the AMMO TRACKING feature to ON.<br />
# Create manually or drag a missile weapon (ex. Longbow) from the Compendium to your sheet.<br />
# Create manually or drag a missile type (Arrows) from the compendium to your sheet<br />
# Expand the missile type (Arrows) by clicking on the "I" information icon that appears when hovering the mouse over the item.<br />
# Select the USE AS RESOURCE checkbox. (ammunition items dragged from the Compendium will have this option automatically checked off)<br />
# On the CORE tab, expand the missile weapon (Long Bow) in the ATTACKS & SPELLCASTING section by clicking on the gear icon that appears when hovering over the attack.<br />
# In the AMMUNITION section put the exact name of the ammunition resource (Arrows). If you want to spend more than one piece of ammunition per shot you want to add the number of pieces after the name of the ammunition resource and a comma. (ex. ''Arrows,2'' )<br />
<br />
<br />
Now, any time the missile weapon (Longbow) is rolled, a piece of ammunition will automatically be spent and the chat will make note. Additionally after the first time the missile weapon is used the AMMUNITION section will update with the ID of the resource repeating section, this is normal and expected.<br />
<br />
<br />
===Automatic Spell Slot Tracking===<br />
<br />
Automatic Spell Slot Tracking is a feature that requires the above Companion API Script. Once installed, follow these instructions to enable automatic spell slot tracking in your game:<br />
* In the chat input area of the Sidebar, type ''!5estatus'' and press Enter, to check if spelltracking is set to 'on'.<br />
* If not, type ''!spelltracking on'' and press Enter to activate this feature.<br />
* Alternatively, you may type ''!spelltracking quiet'' and press Enter to activate this feature, while preventing spelltracking messages from being displayed in the chat.<br />
<br />
<br />
<br />
Once the Spell Slot Tracking has been activated, each time a spell is cast:<br />
# The number of cast spells of the appropriate level is updated in the Spell tab of the character sheet (see [[5th Edition OGL by Roll20|Spell Levels & Spells Per Day]]).<br />
# A message is output in the chat, displaying the spell level, the number of available spell slots and the number of used spell slots for this level.<br />
# Spell slots decrement as spells are cast. <br />
# Spells that are marked as a Ritual do not affect the tally of spell slots when cast.<br />
<br />
<br />
At any time, you can manually adjust this count directly in the Spell Page of the character sheet.<br />
<br />
=Updates=<br />
* {{hc|articles/360037772613-Change-Log Roll20 Changelog}} - Full Changelog of Roll20, updates for 5E sheet are included<br />
* {{fpl|10096810/ D&D 5th Edition by Roll20 (Q2Y2021)}} often has mentions of latest updates<br />
* Major Sheet Updates:<br />
** Feats can now be selected in Charactermancer {{fpl|8891809 June 2020}}<br />
** Game [[creator]] can select which [[compendiums]] are or aren't accessible in a game. [https://app.roll20.net/forum/post/8738570/release-note-for-may-26-2020 May 26 2020]<br />
<br />
=Known Issues=<br />
The sheet has a number of known bugs and issues, some which are mentioned in the sheet's latest forum thread.<br />
<br />
'''Charactermancer/Character Creation'''<br />
* '''Charactermancer & Compendium drag-n-drop doesn't work when sheet is in a separate window.''' This is [[Character_Sheets#Character_Sheet_in_a_separate_window|an inherit limitation to how character sheets work]] at the moment. <br />
* '''Multiclassing & spell selection''' - There are troubles when multiclassing spellcasters and getting to select spells from the right lists.<br />
* '''Duplicate races/classes from Essential Kit appear in selection''' You need to uncheck EK from your compendium for it to no longer appear in selections.<br />
<br />
<br />
'''General:'''<br />
* '''Warlock spell slots''' - The Warlock's spell slots don't work too well with the sheet, and most people use some manual adjustments for how they work. The number of spell slots also appears wrong in the Charactermancer.<br />
* '''NPC stat <code>desc</code> changed into <code>description</code>''' This was a recent update that broke some macros for people, resulting in error messages along: "can't find ''desc'' attribute" {{fpl|8297517/ release notes march 2020}}<br />
<br />
=Sheet Guides=<br />
* [[5E Macros]]<br />
* {{blog|638339117446578176/tome-of-tips-dungeons-dragons-5th-edition-ogl Tome Of Tips: The D&D 5E character sheet}}<br />
* {{yt.be|9BGGr97qJdY|Learning Roll20: EP01 Character Sheets (D&D 5E)}} 50min, by Roll20 (2020)<br />
<br />
=Related Pages=<br />
* D&D 5E by Roll20 sheet<br />
** [[D&D5E by Roll20 NPC Attributes]]<br />
** [[D&D 5e by Roll20 Roll Templates]]<br />
** [[D&D 5E by Roll20: How to setup Ammunition and Resource tracker]]<br />
* [[5E]] - general D&D 5E info for Roll20. Lists also the alterantive character sheets for 5E<br />
* [[D&D]] - Roll20 stuff on the various editions.<br />
* {{Compendium}}<br />
** [[Compendium Sharing]]<br />
* [[Character Vault]]<br />
<br />
=See Also=<br />
* {{repo|Roll20/roll20-character-sheets/tree/master/DD5thEditionLegacy Sheet sourcecode}} - (Public version of sheet code is 1½+ years behind from what is actually used)<br />
* {{hc|articles/360037772613-Change-Log Roll20 Changelog}} - Full Changelog of Roll20, updates for 5E sheet are included<br />
<br /><br />
<br /><br />
[[Category:Character Sheet Documentation]]<br />
[[Category:Official Sheet]]<br />
[[Category:DnD5E]]<br />
[[Category:Featured articles]]</div>5004103https://wiki.roll20.net/Script:ScriptCardsScript:ScriptCards2021-10-05T22:24:27Z<p>5004103: /* Roll Variable Assignment (--=) */</p>
<hr />
<div>{{revdate}}<br />
== Introduction ==<br />
'''ScriptCards''' provides a script interpreter that can be used to create powerful macros that display the results of player/NPC actions, or display other information in a pleasing visual format in your game's chat window. The scripting language contains variables (both dice-roll (enhanced numerics) and strings) as well, conditionals, branching, subroutines with parameters, and a set of built-in functions to simplify working with Roll20 information.<br />
{{script overview<br />
|name=ScriptCards<br />
|author={{user profile|2365448|Kurt J.}}<br />
|code=<br />
|version=1.4.0e<br />
|lastmodified=2021-09-24}}<br />
ScriptCards is not game-system specific, and can be used with any system/sheet. Near the end of this Wiki there is a section set aside for libraries that can implement system-specific tasks, with the hope that enthusiasts playing particular systems will create and share utility functions that can be utilized by the wider community.<br />
<br />
The default display style for ScriptCards output is similar to the format used to document player and NPC abilities in Dungeons and Dragons 4th Edition, but does not have any system ties to D&D4E.<br />
<br />
Current OneClick Version : 1.4.0e<br />
<br />
Current Development Version : 1.4.4<br />
<br />
'''''<big>Critically Important: ScriptCards does not use/parse inline rolls. ScriptCards includes its own built-in dice roll parser to allow for the use of variables inside dice rolls. As of version 1.2.3, ScriptCards will now take inline rolls and substitute the total result value in statement strings, meaning that you can utilize inline rolls but ScriptCards will only see the result of the roll, and not parse the roll components itself.</big>'''''<br />
<br />
* {{fpl|9752053/ ScriptCards thread}}<br />
** {{fpl|10000297/ Scritpcard API Working and Sharing}}<br />
* https://github.com/kjaegers/ScriptCards/tree/main/ScriptCards_API - GitHub repository for source before the one-click version is updated.<br />
* {{yt.be|hyR7Jnq4mQM ScriptCards Intro}} 45min, Jan 2021<br />
* {{yt.be|u50xvNzS9Zk ScriptCards Magic Missile Deep Dive}} 39min, Feb 2021<br />
<br />
<br />
__TOC__<br />
=== Is ScriptCards Related to [[PowerCards]]? ===<br />
<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
Check the '''[[#What to Know if you are Coming from PowerCards|What to Know if you are Coming from PowerCards]]'''-section for a comparison table between the two scripts.<br />
<br />
== What is a ScriptCard Script ==<br />
<br />
A ScriptCard Script is text written into the chat window (either typed directly, pasted, or run via a macro) that will produce a card of information in the [[text Chat|chat window]]. A ScriptCard Script is composed of an [[API]] command: <code><nowiki>!scriptcard {{ }}</nowiki></code> enclosing any number of lines that determine the output that will be added to the card. At it simplest, the following macro:<br />
<br />
<pre>!scriptcard {{ }}</pre><br />
<br />
Will produce just a title card that displays “ScriptCards” as the name:<br />
<br />
[[File:Scriptcard blank.png]]<br />
<br />
Of course, this is just the simplest type of macro and isn’t very useful. In order to produce useful output, we need to include lines between the <code><nowiki>{{</nowiki></code> and <code><nowiki>}}</nowiki></code> that direct the API script as to what it should do.<br />
<br />
== Structure of a ScriptCard Line ==<br />
<br />
All ScriptCard lines begin with two dashes, followed by an ''statement identifier character'' that lets ScriptCards what type of line it is. There are several of these, and they are detailed in the next section. After the line type identifier, a Tag name 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.<br />
<br />
Following the Tag is a vertical bar, and then the content of the line itself. Again, each type of line might interpret this content differently.<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Identifier !! Statement Type !! Tag !! Content !! Notes<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--/</nowiki> || Comment || unused || unused || The <code>--/</code> 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--#</nowiki> || 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").<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--+</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--=</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--&</nowiki> || Assign String 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. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--@</nowiki> || 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 (i.e., [[TokenMod|!token-mod]], or [[ChatSetAttr|!setattr]], etc.)<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--:</nowiki> || 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<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--^</nowiki> || Branch To || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--></nowiki> || Call Procedure || 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<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--<</nowiki> || 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.<br />
|- <br />
| style="white-space:nowrap" | <nowiki>--?</nowiki> || Conditional Branch || Condition to be evaluated || True Branch Label<nowiki>|</nowiki>False Branch Label || The condition will be evaluated and execution will jump to one of the two indicated branches (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 included a semicolon separated list of parameters. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--s</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--l</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--v</nowiki> || 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+'''''<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--e</nowiki> || Echo to Chat || Name to send chat command as || Chat message to send || Variable substitution takes place on the tag and content.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--R</nowiki> || Retrieve Repeating Section Row information || "find", "first", or "next" || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--~</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--c</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--i</nowiki> || Information Request || User Prompt;Button Caption || InfoType;VariableName;ParameterText || See full documentation below.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--d</nowiki> || 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. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--%</nowiki> || 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. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--*</nowiki> || 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.<br />
|}<br />
<br />
== ScriptCard Statement Type Details ==<br />
The sections below detail the individual statement types supported by ScriptCards<br />
<br />
=== Comment (--/) ===<br />
<br />
A --/ statement is ignored by the ScriptCards parser. You can use this type of statement to add comments and informational text to your script. <br />
<br />
Example:<br />
<pre><br />
!script {{<br />
--/|Script Name : Fireball<br />
--/|Purpose : Allow the player to cast a fireball and blow stuff up!<br />
.<br />
.<br />
.<br />
}}<br />
</pre><br />
<br />
=== Set Parameter (--#) ===<br />
<br />
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.<br />
<br />
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.<br />
<br />
'''''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.'''''<br />
<br />
Examples:<br />
<pre><br />
--#title|Magic Missile<br />
--#leftsub|Level 1 Spell<br />
--#rightsub|Force Damage<br />
</pre><br />
<br />
The three examples above set the “title”, “leftsub”, and “rightsub” values for the card to the content value for the line. <br />
<br />
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.<br />
Settings Lines do not produce output lines on the card.<br />
<br />
The following settings are available (note that parameter names are ''not'' case sensitive):<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Name !! Effect/Use !! Default Value !! Type<br />
|-<br />
| 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<br />
|-<br />
| allowplaintextinrolls || If set to a non-zero value, plain character text in rolls will be copied to the roll text || 0 || Per-Line<br />
|-<br />
| bodyFontFace || Name of the font used in the card rows || Helvetica || Global<br />
|-<br />
| bodyFontSize || Size of the text in the card rows || 14px || Global<br />
|-<br />
| bodybackgroundimage || Specify an image (content for a CSS background-image tag) for the body area || none || Global<br />
|-<br />
| buttonBackground || Background color for buttons created with [button][/button] || #1C6EA4 || Per-Line<br />
|-<br />
| buttonBorderColor || Border (outline) color for buttons created with [button][/button] || #999999 || Per-Line<br />
|-<br />
| buttonFontFace || Font Family specifier for captions on buttons created with [button][/button] || Tahoma || Per-Line<br />
|-<br />
| buttonFontSize|| Text size for captions on buttons created with [button][/button] || x-small || Per-Line<br />
|-<br />
| buttonTextColor|| Text color of labels on buttons created with [button][/button] || #FFFFFF || Per-Line<br />
|-<br />
| 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<br />
|-<br />
| deferralcharacter || Changes the meta script deferral sequence to the specified value || ^ || Per-Line<br />
|-<br />
| diceFontColor|| Color of the dice created with the [d4] [d6], etc. formatting markers || #1C6EA4 || Per-Line<br />
|-<br />
| dicefontsize || Size of the dice created with the [d4] [d6], etc. formatting markers || 3.0em || Per-Line<br />
|-<br />
| 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<br />
|-<br />
| disablerollprocessing || If set to a non-zero value, --= lines will not process dice rolls strings || 0 || Per-Line<br />
|-<br />
| emoteBackground || Background color of the emote area || #f5f5ba || Global<br />
|-<br />
| emoteFont || Name of the font used in emote area (above the title of the output card) || Georgia || Global<br />
|-<br />
| emoteFontColor || Color of the font in the emote area || None (Empty) || Global<br />
|-<br />
| emoteFontSize || Size of the font used in the emote area || 14px || Global<br />
|-<br />
| emoteFontWeight || Font weight for the font in the emote area || bold|| Global<br />
|-<br />
| emoteState || If set to anything other than "visible", the emote portion of the card will not be displayed || visible || Global<br />
|-<br />
| emoteText || Text to display in the emote portion of the card || None (Empty) || Global<br />
|-<br />
| emotefont || Name of the font used in the emote text area || font-family: Georgia, serif; font-weight: bold; || Global<br />
|-<br />
| evenRowBackground || Hex code for the background color for even rows || #eeeeee || Per-Line<br />
|-<br />
| evenRowFontColor || Hex code for the text color for even rows || #000000 || Per-Line<br />
|-<br />
| evenrowbackgroundimage || Specify an image (content for a CSS background-image tag) for the even card rows || none || Per-Line<br />
|-<br />
| executionlimit || Maximum number of script lines the interpreter will try to execute. This prevents "infinite loop" sandbox crashes || 40000 || Global<br />
|-<br />
| hideCard || If set to any non-default value, the entire card output will be suppressed || 0 || Global<br />
|-<br />
| 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<br />
|-<br />
| 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<br />
|-<br />
| lineheight || Vertical size of each line on the output card || normal || Per-Line<br />
|-<br />
| nominmaxhighlight || If set to anything other than "0", rolls will not display crit/fumble/mixed highlight colors. || 0 || Per-Line<br />
|-<br />
| norollhighlight || If set to anything other than "0", rolls will not be formatted (plain numbers) but will still get a tooltip with details ('''''v1.3.6b+''''') || 0 || Per-Line<br />
|-<br />
| oddRowBackground || Hex code for the background color for even rows || #d0e4f5 || Per-Line <br />
|-<br />
| oddRowFontColor || Hex code for the text color for odd rows || #000000 || Per-Line<br />
|-<br />
| oddrowbackgroundimage || Specify an image (content for a CSS background-image tag) for the odd crd rows || none || Per-Line<br />
|-<br />
| reentrant || Used to name a script for rentrant button use || 0 || Global<br />
|-<br />
| 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)0 || Global<br />
|-<br />
| rollhilightlineheight || Determines the height of the hilight box placed around roll results ('''''1.4.2+''''') || 1.0em || Per-Line<br />
|-<br />
| roundUp || If set to a non-default value, integer division will round up instead of down || 0 || Per-Line<br />
|-<br />
| showfromfornonwhispers || If set to a non-zero value, will include the sender on cards that aren't whispered || 0 || Global<br />
|-<br />
| 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<br />
|-<br />
| subtitleFontColor || Color of the text in the subtitle areas || #FFFFFF || Global<br />
|-<br />
| subtitleFontFace || Name of the font used on the subtitle sections || Tahoma || Global<br />
|-<br />
| subtitleFontSize || Size of the subtitle font || 13px || Global<br />
|-<br />
| subtitleSeperator || The character(s) that will be placed between leftsub and rightsub || <nowiki>&#x2666</nowiki>; || Global<br />
|-<br />
| tableBorderRadius || CSS specifier for how rounded the borders of the output card are. Use "0px;" for square borders || 6px; || Global<br />
|-<br />
| tableShadow || CSS specifier for the drop shadow under the output card || 5px 3px 3px 0px #aaa; || Global<br />
|-<br />
| tablebgcolor || Background color of the whole card. '''''Normally not visible''''' || #EEEEEE || Global<br />
|-<br />
| tableborder || Color of the border that surrounds the whole card || 2px solid #000000; || Global<br />
|-<br />
| 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<br />
|-<br />
| timezone || IANA Specifier for the local time zone, used in system/date functions || merica/New_York || Per-Line<br />
|-<br />
| title || Text displayed in the title area of the card || ScriptCards || Global<br />
|-<br />
| titleCardBackground || A hex color code representing the background color of the title area. || #1c6ea4 || Global<br />
|-<br />
| titleFontColor || Color of the text on the card title || #FFFFFF || Global<br />
|-<br />
| titleFontFace || Name of the font used on the title area || Contrail One || Global<br />
|-<br />
| titleFontLineHeight || Line spacing on the title area || 1.2em || Global<br />
|-<br />
| titleFontSize || Size of the title font || 1.2em || Global<br />
|-<br />
| titlecardbackgroundimage || Specify an image (content for a CSS background-image tag) for the title card area || none || Global<br />
|-<br />
| titlecardbottomborder || Border CSS specifier for the bottom of the title card area || 2px solid #444444; || Global<br />
|-<br />
| titlecardgradient || If set to non-zero value, will place a vertical gradient on the title card area || 0 || Global<br />
|-<br />
| usehollowdice || If set to a non-zero value, the hollow/outline versions of the dice fonts will be used || 0 || Per-Line<br />
|-<br />
| whisper|| Comma separated list of who to whisper the output to. Use "gm" for [[GM|GMs]] and "self" for the sender || none || Global|}<br />
|}<br />
<br />
''Setting Lines do not produce output lines on the card''<br />
<br />
=== Direct Output (--+) ===<br />
<br />
A direct output line display 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.<br />
<br />
Examples of Direct Output lines:<br />
<pre><br />
--+Hello|World<br />
--+Attack|The monster rolls [$Attack] to hit!<br />
--+Damage|@{target|token_name} is hit for [$Damage] [#3333AA][b]frost[/b][/#] damage.<br />
</pre><br />
<br />
Direct Output lines support inline formatting, roll variable replacement, character attribute references, and procedure variables.<br />
<br />
=== GM Output (--*) ===<br />
<br />
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. <br />
<br />
Example:<br />
<pre><br />
--+PlayerLine|This line is shown on the public card<br />
--*GMLine|This line will only be shown to GMs, on a separate card.<br />
</pre><br />
<br />
=== Roll Variable Assignment (--=) ===<br />
<br />
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.<br />
<br />
'''''All components of a roll equation should be separated with spaces.'''''<br />
<br />
Examples:<br />
<pre><br />
--=MissileDamage|1d4 + 1<br />
--=Attack|1d20 + @{selected|strength_mod} [STR] + @{selected|pb} [PROF]<br />
</pre><br />
<br />
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. Text enclosed in square brackets ([]) is considered "flavor text" and will be added to the result text but does not impact the roll result.<br />
<br />
The following dice formats are supported:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Format Pattern !! Example !! Description<br />
|-<br />
| XdY || 3d8 || Simple format. Roll a Y-sided die X times<br />
|-<br />
| XdYkhZ || 2d20kh1 || Roll Y-sided die X times and keep the highest Z number of dice<br />
|-<br />
| XdYklZ || 4d6kl3 || Roll Y-sided die X times and keep the lowest Z number of dice <br />
|-<br />
| XdY>Z || 5d6>3 || Roll Y-sided die X times and count a 1 for each roll greater than Z <br />
|-<br />
| XdY<Z || 5d6<3 || Roll Y-sided die X times and count a 1 for each roll less than Z <br />
|}<br />
<br />
'''''Note: The dice formulae below are supported in the development version of ScriptCards and will be merged with the table above when activated on OneClick'''''<br />
::{| class="wikitable"<br />
|-<br />
! Format Pattern !! Example !! Description<br />
|-<br />
| 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<br />
|-<br />
| 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<br />
|-<br />
| 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)<br />
|-<br />
| 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<br />
|}<br />
<br />
The following operators are supported in a roll equation:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Operator !! Operation<br />
|-<br />
| + || Addition <br />
|-<br />
| - || Subtraction <br />
|-<br />
| * || Multiplication <br />
|-<br />
| / || Division <br />
|-<br />
| \ || Integer Division (Rounds down) <br />
|-<br />
| % || Modulo (Remainder of Divison)<br />
|}<br />
<br />
Roll Variables can be accessed at any time after they have been created by using the [$VariableName] format, with the following optional modifiers:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Modifier !! Meaning<br />
|-<br />
| No modifier || In a Direct Output Line (<nowiki>--+</nowiki>) 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<br />
|-<br />
| .Total || The end result of the roll equation as an unformatted number <br />
|-<br />
| .Base || The cumulative result of any dice rolled in the Roll Text (Numeric modifiers are not included) <br />
|-<br />
| .Ones || The number of dice in the roll that came up as 1s <br />
|-<br />
| .Aces || The number of dice in the roll that came up as the maximum number on the die <br />
|-<br />
| .Odds || The number of dice in the roll that came up with an odd number <br />
|-<br />
| .Evens || The number of dice in the roll that came up with an even number <br />
|-<br />
| .RollText || The raw text of the roll that was use to generate the results <br />
|-<br />
| .Text || A text representation of the results of the roll, including the numbers rolled for each die <br />
|-<br />
| .tableEntryText || The text portion of the result of a table roll<br />
|-<br />
| .tableEntryImgURL || The image source portion of the result of a table roll<br />
|-<br />
| .tableEntryValue || Numeric value of tableEntryText (via parseInt). If a non-numeric value, will be 0<br />
|-<br />
| .Raw || The total numeric result without any formatting, even if placed somewhere formatting would normally be done. <br />
|}<br />
<br />
Examples:<br />
<pre><br />
--+Total Damage|[$MissileDamage.Total] (roll was 1d4+1)<br />
--+Base Damage|[$MissileDamage.Base] (without the +1)<br />
--=Attack|1d20 + @{selected|strength_mod} [STR] + @{selected|pb} [PROF] + [$BlessBonus] [Bless]<br />
</pre><br />
<br />
In this case, 1d4 will be rolled and stored in “BlessBonus”, which can then be used in the Attack line.<br />
<br />
'''''Mathematical Functions in Roll Expressions '''''<br />
<br />
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:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Expression !! Meaning<br />
|-<br />
| {ABS} || Absolute Value<br />
|-<br />
| {CEIL} || Ceiling value (round up to the next whole number)<br />
|-<br />
| {FLOOR} || Floor value (round down to the next whole number)<br />
|-<br />
| {ROUND} || Round value (round up if the decimal portion is greater than 0.5, otherwise round down)<br />
|-<br />
| {NEGATE} || Multiply the value by negative one.<br />
|-<br />
| {SQRT} || Take the square root of the running value. ('''''1.4.1+''''')<br />
|-<br />
| {SQUARE} || Square the running value. ('''''1.4.2+''''')<br />
|-<br />
| {CUBEROOT} || Take the cube root of the running value. ('''''1.4.2+''''')<br />
|-<br />
| {CUBE} || Cube the running value. ('''''1.4.2+''''')<br />
|-<br />
| {SIN} || Return the SIN of running value. ('''''1.4.2+''''')<br />
|-<br />
| {COS} || Return the COS of running value. ('''''1.4.2+''''')<br />
|-<br />
| {TAN} || Return the TAN of running value. ('''''1.4.2+''''')<br />
|-<br />
| {ASIN} || Return the ASIN of running value. ('''''1.4.2+''''')<br />
|-<br />
| {ACOS} || Return the ACOS of running value. ('''''1.4.2+''''')<br />
|-<br />
| {ATAN} || Return the ATAN of running value. ('''''1.4.2+''''')<br />
|}<br />
<br />
Here are the syntax rules when using the above listed functions:<br />
<br />
Example 1.<br />
<br />
<pre><br />
!script {{<br />
--=output|2.9 {FLOOR}<br />
--+output|[$output]<br />
}}<br />
</pre><br />
<br />
The output from this example is "2".<br />
<br />
Example 2.<br />
<br />
<pre><br />
!script {{<br />
--=output|2.9 {FLOOR} {NEGATE} - 3<br />
--+output|[$output]<br />
}}<br />
</pre><br />
<br />
The output from this example is "-5".<br />
<br />
Basically, a function will use as its input whatever the current "running total" is.<br />
<br />
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.<br />
<br />
<br />
'''''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 <nowiki>[[ ]]</nowiki> 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.<br />
<br />
'''''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.<br />
<br />
'''Rolling on Rollable Tables'''<br />
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.<br />
<br />
''Roll Variable Lines do not produce output lines on the card.''<br />
<br />
=== String Variable Assignment (--&) ===<br />
<br />
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:<br />
<br />
<pre><br />
--&MyText|Hello<br />
</pre><br />
<br />
Here, we assign the text "Hello" to the string variable named MyText. You can also append text to a string variable by prefixing the content with a + sign:<br />
<br />
<pre><br />
--&MyText|+ World<br />
</pre><br />
<br />
If run after the statement above, MyText will now contain "Hello World".<br />
<br />
String variables can be referenced using the syntax [&variablename]<br />
<br />
=== Call API (--@) ===<br />
<br />
ScriptCards can use a Call API instruction to execute other API commands. The Tag contains the API 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 API command is executed.<br />
<br />
Examples:<br />
<pre><br />
--@eh|list<br />
--@alter|_target|@{target|token_id} _bar|3 _amount|-[$Damage]<br />
</pre><br />
<br />
In the first example above, the command <code>!eh list</code> will be executed, calling [[EncounterHelper]]. In the second, {{fpl|1216260/ AlterBars}} is called to modify a token's Bar 3 value.<br />
<br />
'''''Note:''''' When ScriptCards (or any API script) runs other API 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).<br />
<br />
See [[API:Script Index]] for more options.<br />
<br />
=== Branch Label (--:) ===<br />
<br />
A branch label defines a line in your code that can be reached by one of the branching instructions (<nowiki>--^</nowiki>, <nowiki>--></nowiki>, or <nowiki>--?</nowiki>). The Tag serves as the label name, and must be unique on the card.<br />
<br />
The vertical bar (|) separator must be present, but the content portion of the line is unused and can be treated as a comment.<br />
<br />
Examples:<br />
<pre><br />
--:MyLoop|<br />
--:CriticalHit|Will jump here if we roll a critical hit!<br />
</pre><br />
<br />
''A Branch Label line does not produce an output line on the card.''<br />
<br />
=== Branch (--^) === <br />
<br />
A Branch line 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.<br />
<br />
Examples:<br />
<pre><br />
--^MyLoop|Jumps to MyLoop<br />
--^SkipCrit|We didn't crit, so skip the Crit code<br />
</pre><br />
<br />
''A Branch line does not produce an output line on the card.''<br />
<br />
=== Call Procedure (-->) ===<br />
<br />
Similar to a branch, a Call Procedure (sometimes knows 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 (<nowiki>--<</nowiki>) 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 (;).<br />
<br />
Examples:<br />
<pre><br />
-->FixFormat|#3333FF;#999999<br />
</pre><br />
<br />
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%].<br />
<br />
=== Return (--<) ===<br />
<br />
A return instruction marks the end of a Gosub procedure. 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.<br />
<br />
Examples:<br />
<pre><br />
--<|<br />
--<|End of MySub<br />
</pre><br />
<br />
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.<br />
<br />
=== Conditional Statement (--?) ===<br />
<br />
A conditional statement contains some equation in the Tag that will be evaluated. '''''If any part of the comparison can/does contain a space, it needs to be surrounded by double quotes'''''<br />
<br />
Based on the true/false result of the evaluation, one of two execution paths will be taken. These execution paths are detailed in the content section of the statement. The "if true" path is specified first (directly after the vertical bar), and the "if false" path is specified after it, also separated by a vertical bar.<br />
<br />
Example:<br />
<pre><br />
--?[$AttackRoll.Total] -ge [$TargetAC]|Hit|Miss<br />
</pre><br />
<br />
'''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.'''<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Branch Format !! Meaning<br />
|-<br />
| Label || If just a label is specified, execution will branch to that label when the comparison is matched.<br />
|-<br />
| >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 <br />
|-<br />
| =VariableName || The roll variable "VariableName" will be assigned the value following a semicolon (ex: --?1 -eq 1|=Roll;1d20)<br />
|-<br />
| &VariableName || The string variable "VariableName" will be assigned the value following a semicolon (ex: --?1 -eq 1|&Result;Hit|&Result;Miss)<br />
|-<br />
| % or %! || The current for...next loop will perform the "next" action (%) or will break out (%!) <br />
|-<br />
| [ || Code block (see below)<br />
|}<br />
<br />
Examples:<br />
<pre><br />
--?[$AttackRoll.Base] -eq 20|CriticalHit<br />
--?[$AttackRoll.Base] -eq 1|>Fumble;@{selected|dexterity_mod}<br />
--?"@{target|npc_type}" -inc "undead"|&MonsterType;Undead|&MonsterType;Not Undead<br />
--?[$Attack.Total] >= [$ArmorClass]|>Hit|>Miss<br />
</pre><br />
<br />
In the first example, if the Base value of AttackRoll is a 20 (natural 20 on the die) execution will branch to the CriticalHit label.<br />
<br />
In the second example, 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%].<br />
<br />
The third example looks for the word "undead" in the npc_type attribute of the targeted character. If it exists in the text, the MonsterType string variable will be set to "Undead", otherwise it will be set to "Not Undead". <br />
<br />
The final example would call 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.<br />
<br />
''Text that does/may contain a space should be enclosed in double quotes.''<br />
<br />
The following comparison operators are available:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Comparator !! Meaning<br />
|-<br />
| -eq || Equal To <br />
|-<br />
| -eqi || Case insensitive Equal To <br />
|-<br />
| -ne || Not Equal To <br />
|-<br />
| -nei || Case insensitive Not Equal To <br />
|-<br />
| -gt || Greater Than <br />
|-<br />
| -ge || Greater Than or Equal To <br />
|-<br />
| -lt || Less Than <br />
|-<br />
| -le || Less Than or Equal To <br />
|-<br />
| -inc || Includes (text strings). <br />
|-<br />
| -ninc || Does Not Include (text strings). <br />
|}<br />
<br />
Multi-part conditionals are supported with -and and -or as separators. For example:<br />
<br />
<pre><br />
--?[$Attack.Total] -ge @{target|npc_ac} -and [$Attack.Base] -ne 20|HitButNotCrit<br />
</pre><br />
<br />
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):<br />
<br />
true AND false OR true<br />
<br />
Will be evaluated as true. The first two (true and false) will be false, but then false OR true will be true.<br />
<br />
Conversely:<br />
<br />
true or false and false<br />
<br />
Will be false, because the first true and false will evaluate to true, and then true and false will be false.<br />
<br />
'''CODE BLOCKS'''<br />
<br />
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.<br />
<br />
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:<br />
<br />
<pre><br />
!script {{<br />
--=Roll|1d2<br />
--+Roll|[$Roll]<br />
--?[$Roll.Total] -eq 2|[<br />
--&Value|Yep!<br />
--+|We are inside the TRUE portion of the block<br />
--]|[<br />
--&Value|Nope<br />
--+|We are inside the FALSE portion of the block<br />
--]|<br />
--+After|the blocks!<br />
--+Value|[&Value]<br />
}}<br />
</pre><br />
<br />
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 --]|. <br />
<br />
At this time, blocks cannot be nested, and can only be created as part of a conditional (--[ is not a valid statement type)<br />
<br />
''A conditional statement does not produce a line of output on the card.''<br />
<br />
=== Case Statement (--c) ===<br />
<br />
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 (:). Each match condition includes a branch label that will be used if the test value matches the item. 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:<br />
<br />
<pre><br />
!script {{<br />
--#title|Case Statement Testing<br />
--=Roll|1d4<br />
--C[$Roll.Total]|1:>One;[$Roll]|2:>Two;[$Roll]|3:>Three;[$Roll]|4:>Four;[$Roll]<br />
--X|<br />
<br />
--:One| --+Value|was One ([%1%]) --<|<br />
--:Two| --+Value|was Two ([%1%]) --<|<br />
--:Three| --+Value|was Three ([%1%]) --<|<br />
--:Four| --+Value|was Four ([%1%]) --<|<br />
}}<br />
</pre><br />
<br />
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 variable as a parameter.<br />
<br />
=== Save and Load (--s and --l) ===<br />
<br />
This statement pair is used to either store (--s) or load (--l) data from persistent storage. Items stored in persistent storage remain between card rolls and between Roll20 sessions. There are two types of data that can be stored: settings and roll variables. <br />
<br />
Examples:<br />
<br />
<pre><br />
--Ssettings|GreenStyle<br />
--Srollvariables|FirstCardVars<br />
</pre><br />
<br />
In this case, the tag for the statement determines what type of item is being saved (settings or rollvariables). When saving settings, all non-default settings are written to the named setting storage value. When Roll Variables are saved, all variables that currently exist will be saved to the named storage value.<br />
<br />
Loading stored items simply requires the same command with the --l statement type:<br />
<br />
<pre><br />
--Lsettings|GreenStyle<br />
--Lrollvariables|FirstCardVars<br />
</pre><br />
<br />
When loading settings, all stored settings will be applied to the current card settings. You can override settings by changing them after the load.<br />
<br />
When loading roll variables, the saved variables will be added to (or overwrite if they have the same name) any variables on the current card. This means it is safe to create roll variables before the load statement.<br />
<br />
'''Practical Uses'''<br />
The major intended use of persistent storage is for storing card formats for use in later scripts. For example, the following script:<br />
<br />
<pre><br />
!scriptcard {{<br />
--#titlecardbackground|#22CC22<br />
--#oddrowbackground|#cceecc<br />
--#evenrowbackground|#99ee99<br />
--Ssettings|@{selected|token_name}<br />
}}<br />
</pre><br />
<br />
Would save the titlecardbackground, oddrowbackground, and evenrowbackground settings to a saved list named after the selected token's name. When creating cards for that token to run later, you could include the line:<br />
<br />
<pre><br />
--Lsettings|@{selected|token_name}<br />
</pre><br />
<br />
To load all of the settings at once. By creating these setting sets for each character, you can specify a different color scheme for each character that can then be used in cards with a single formatting line.<br />
<br />
There is a supplemental ! command added to support saved settings:<br />
<br />
<pre><br />
!sc-liststoredsettings<br />
</pre><br />
<br />
Will produce a list of all stored setting names, with buttons to list the setting values stored in each group and a button to delete groups as needed.<br />
<br />
=== Visual Effects (--v) ===<br />
<br />
The --v statement can be used to create visual effects on the tabletop. The tag portion of the statement can be either "token" or "betweentokens". The content portion of the statement contains the required parameters for the effect generation, separated by spaces. If the effect is "none", no effect will be played. If any other value that doesn't match a Roll20 effect name will result in a burst-fire effect.<br />
<br />
For "token" effects, the parameters are the token id for the token the effect happens on, followed by the effect specifier.<br />
<br />
Example:<br />
<pre><br />
--vtoken|@{selected|token_id} burst-fire<br />
</pre><br />
<br />
For "betweentoken" effects, the parameters are the source token id, the target token id, and the effect specifier.<br />
<br />
Example:<br />
<pre><br />
--vbetweentokens|@{selected|token_id} @{target|token_id} beam-magic<br />
</pre><br />
<br />
'''''Version 1.2.8+'''''<br />
<br />
An additional effect specifier, "point" is available in 1.2.8+. This specifier allows you to create a visual effect at a designated X/Y pixel coordinate. Future updates will add custom-vfx support to this option. The parameters are the X and Y coordinates and the effect descriptor. As of version 1.2.9, you can also use custom effect specifiers with Point effects:<br />
<br />
<pre><br />
--vpoint|150 200 burst-fire<br />
</pre><br />
<br />
=== Echo to Chat (--e) ===<br />
<br />
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.<br />
<br />
Example:<br />
<pre><br />
--eThe Ghost|/em hovers around @{selected|character_name}... BOO!<br />
</pre><br />
<br />
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).<br />
<br />
'''''Whispering'''''<br />
<br />
You can use the echo statement to send a whisper, but there's a trick to it. If you execute this code here:<br />
<br />
<pre><br />
--eThe Ghost|/w ExamplePlayerName Boo.<br />
</pre><br />
<br />
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.<br />
<br />
So, in conclusion, it's best to use something like this when you're sending a whisper:<br />
<br />
<pre><br />
!script {{<br />
--#hidecard|1<br />
--&sender|The Ghost<br />
--&receiver|ExamplePlayerName<br />
--&message|Boo.<br />
--e[&sender]|/w [&receiver] [&message]<br />
--eScriptCards|/w gm **Whispered from [&sender] to [&receiver]:** [&message] <br />
}}<br />
</pre><br />
<br />
This will ensure that the message appears in your chat feed as well.<br />
<br />
=== Repeating Section Access (--R) ===<br />
<br />
ScriptCards (as of v0.0.13) supports accessing repeating section rows on a character sheet (for example: the attacks, the items, and the repeating resources) with the --R statement type. <br />
<br />
There are three basic commands you can use with --R, and they are specified by <br />
the tag used:<br />
<br />
<br />
'''''The "find" tag'''''<br />
<br />
An Rfind statement is used to search through a repeating field. Here is the general form of such a statement.<br />
<br />
<pre><br />
--Rfind|characterid;EntryName;SectionPrefix;SearchField<br />
</pre><br />
<br />
This is the most direct way to access a repeating section row. Supplying the character ID, followed by what you are looking for (Greatsword, for example), followed by the character sheet's section prefix (repeating_attack), followed by the field to check what you are searching for (atkname) will load the matching section (if found) into the script parsers memory. For example:<br />
<br />
<pre><br />
--Rfind|@{selected|character_id};Greatsword;repeating_attack;atkname<br />
</pre><br />
<br />
Will look at the character's "repeating_attack" section for an entry with an atkname value equal to "Greatsword". Similarly:<br />
<br />
<pre><br />
--Rfind|@{selected|character_id};Bite;repeating_npcaction;name<br />
</pre><br />
<br />
Will look for a "Bite" action on an NPC's action list.<br />
<br />
<br />
'''''The "first" tag'''''<br />
<br />
<pre><br />
--Rfirst|characterid;section prefix<br />
</pre><br />
<br />
This form of the --R command will look at all of the entries in the specified repeating section and load the first one into memory:<br />
<br />
<pre><br />
--Rfirst|@{selected|character_id};repeating_attack<br />
</pre><br />
<br />
Would load the character's first "repeating_attack" row into memory.<br />
<br />
<br />
'''''The "next" tag'''''<br />
<br />
<pre><br />
--Rnext|<br />
</pre><br />
<br />
No parameters are required for --Rnext, which loads the next entry in the list that was obtained with "first" into memory.<br />
<br />
<br />
'''''Section prefixes and how to use them'''''<br />
<br />
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 open [[D&D 5E by Roll20|this page]], and search for the phrase "repeating sections".<br />
<br />
<br />
'''''Additional information'''''<br />
<br />
However a row is obtained, it will be parsed to replace any attribute references (ie, @{level}) with the corresponding character attribute.<br />
<br />
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".<br />
<br />
You can reference repeating attribute data using the syntax [*R:attributename] syntax (similar to referencing standard character attributes).<br />
<br />
Here are some examples:<br />
<br />
Display the details of the "Greatsword" PC attack:<br />
<br />
<pre><br />
!script {{<br />
--Rfind|@{selected|character_id};Greatsword;repeating_attack;atkname<br />
--+Attack Name|[*R:atkname]<br />
--+Base Damage|[*R:dmgbase]<br />
}}<br />
</pre><br />
<br />
[[File:Scriptcards repeating greatsword.png|Repeating Greatsword Attack]]<br />
<br />
List all of the actions an NPC can take (just actions, not legendary, etc.)<br />
<br />
<pre><br />
!script {{<br />
--#title|NPC Actions<br />
--#leftsub|@{selected|token_name}<br />
--Rfirst|@{selected|character_id};repeating_npcaction<br />
--:DisplayLoop|<br />
--?"[*R:name]" -eq NoRepeatingAttributeLoaded|Done<br />
--+Action:|[*R:name] [*R:attack_damage] [*R:attack_damagetype]<br />
--?"[*R:attack_damage2]" -eq ""|NoSecondaryDamage<br />
--+ |[*R:attack_damage2] [*R:attack_damagetype2]<br />
--:NoSecondaryDamage|<br />
--Rnext|<br />
-->DisplayLoop| <br />
--:Done|<br />
}}<br />
</pre><br />
<br />
[[File:Scriptcards repeating npcactions.png]]<br />
<br />
In the script above, we get the "first" repeating_npcaction and display information about it. We then execute "next" and repeat until we run into "NoRepeatingAttributeLoaded".<br />
<br />
See the section named [[#Repeating Section Values|Repeating Section Values]] for more information.<br />
<br />
<br />
'''''Special debugging command: dump'''''<br />
<pre><br />
--Rdump|<br />
</pre><br />
<br />
The "dump" command will list all of the attributes ScriptCards knows about for the currently loaded repeating row to the API Console Log.<br />
<br />
=== Assign Variable to Built-In Function (--~) ===<br />
<br />
ScriptCards has the ability to run a function built into the API script and return the results to a variable. Some functions return roll variables, while others return strings. See the function table below for details. The format is:<br />
<br />
--~VariableName|function;param1;param2;param3;...<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Function Name !! Parameters !! Description<br />
|-<br />
| distance || token_A_ID;token_B_ID || Calculate the Chebyshev distance in grid units between two tokens. This is the measurement scheme D&D 4E/5E use for diagonal distance measurement<br />
|-<br />
| euclideandistance || token_A_ID;token_B_ID || Calculate the Euclidean distance between two tokens. This is essentially the Pythagorean theorem in action. Returns the result in grid units.<br />
|-<br />
| euclideanpixel || token_A_ID;token_B_ID || Calculate the Euclidean distance between two tokens and returns the result is pixels instead of grid units. <br />
|-<br />
| euclideanlong || token_A_ID;token_B_ID || 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 is calculated instead of before. More accurate over long distances. <br />
|-<br />
| manhattandistance || token_A_ID;token_B_ID || Also called "taxicabdistance" (which is an acceptable function name), this measures to how-many-over, how-many-up/down distance, disallowing diagonal movement.<br />
|-<br />
| getselected || none || 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 the first selected token, VariableName2 the second, etc.<br />
|}<br />
<br />
'''''Functions with Sub Functions'''''<br />
<br />
Most ScriptCards functions are grouped into set as sub functions. The table below lists the major functions and their sub functions.<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Function Name !! Sub Function !! Parameters !! Return Type !! Description<br />
|-<br />
| array || define || arrayname;value1;value2;... || none || Creates an array called "arrayname" and adds value1, value2, etc. to the array<br />
|-<br />
| array || sort || arrayname || none || Sorts the specified array in place in ascending order<br />
|-<br />
| array || add || arrayname;value1;value2;... || none || Adds value1, value2, ... to the existing array "arrayname"<br />
|-<br />
| array || remove || arrayname;value1;value2;... || none || Removes value1, value2, ... from the existing array "arrayname". Resets the array index to 0.<br />
|-<br />
| array || replace || arrayname;currentvalue;newvalue || none || Replaces all occurrences of "currentvalue" in "arayname" with "newvalue"<br />
|-<br />
| array || setatindex || arrayname;index;newvalue || none || Replaces the array item at index "index" with "newvalue"<br />
|-<br />
| array || getindex || arrayname || stringVariable || Retrieves the current index in "arrayname" and stores it in the supplied string variable<br />
|-<br />
| array || setindex || arrayname;newindex || none || Sets the current index in array "arrayname" to "newindex"<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| array || removeat || arrayname;indexposition || none || Removes the item at index "indexposition" from "arrayname". Resets the current array index to 0.<br />
|-<br />
| array || indexof || arrayname;searchvalue || stringVariable || Searches the array "arrayname" for and item with the value of "searchvalue" and, if found, returns the index of the first matching value or "ArrayError" if not found<br />
|-<br />
| array || getlength || arrayname || stringVariable || Returns the number of items in array "arrayname"<br />
|-<br />
| array || pagetokens || arrayname;tokenid;(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. 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.)<br />
|-<br />
| 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.<br />
|-<br />
| array || stringify || arrayname || stringVariable || Returns all of the items in "arrayname" as a string separated by semicolons (;)<br />
|-<br />
| array || fromstring || arrayname || delimiter;string || Creates an array from "string", splitting "string" on "delimiter" to separate the items<br />
|-<br />
| array || statusmarkers|| arrayname;tokenid || none|| Creates an array (arrayname) of the active statusmarkers (sometimes called Token Markers) for the specified tokenid<br />
|-<br />
| math || angle || math;angle;tokenid;tokenid|| rollVariable || Calculates the angle between two tokens and returns the value in degrees<br />
|-<br />
| math || ceil || math;ceil;value || rollVariable || Rounds '''value''' up to the next integer, dropping any decimal portion of the number<br />
|-<br />
| math || clamp || math;clamp;value;lowerBound;upperBound || rollVariable || Returns '''value''', but restricted to the range of '''loweBound''' and '''upperBound'''.<br />
|-<br />
| math || floor || math;floor;value || rollVariable || Rounds '''value''' down, dropping any decimal portion of the number<br />
|-<br />
| math || max || math;max;valueA;valueB || rollVariable || Returns the larger of '''valueA''' vs '''valueB'''<br />
|-<br />
| math || min || math;min;valueA;valueB || rollVariable || Returns the smaller of '''valueA''' vs '''valueB'''<br />
|-<br />
| math || round || math;round;value || rollVariable || Rounds '''value''' to the nearest integer<br />
|-<br />
| string || length || string;length;stringValue || rollVariable || Returns the length of '''stringValue''' in characters<br />
|-<br />
| string || before || string;before;searchText;stringValue || stringVariable || Searches '''stringValue''' for '''searchText''' and returns the portion of '''stringValue''' prior to that text<br />
|-<br />
| string || after || string;after;searchText;stringValue || stringVariable || Searches '''stringValue''' for '''searchText''' and returns the portion of '''stringValue''' after that text<br />
|-<br />
| string || left || string;left;count;stringValue || stringVariable || Returns the leftmost '''count''' characters of '''stringValue'''<br />
|-<br />
| string || right || string;right;count;stringValue || stringVariable || Returns the rightmost '''count''' characters of '''stringValue'''<br />
|-<br />
| string || replace || string;replace;searchText;replaceText;stringValue || stringVariable || Replaces '''searchText''' in '''stringValue''' with '''replaceText''' and returns the resulting string<br />
|-<br />
| string || replaceall || string;replace;searchText;replaceText;stringValue || stringVariable || Replaces all intances of '''searchText''' in '''stringValue''' with '''replaceText''' and returns the resulting string '''''Requires 1.2.9+'''''<br />
|-<br />
| string || trim || string;trim;stringValue || stringVariable || Removes leading and trailing spaces from stringValue and returns the result. <br />
|-<br />
| string || substring || string;substring;start;count;stringValue || stringVariable || Returns '''count''' characters starting at '''start''' from '''stringValue'''<br />
|-<br />
| 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.<br />
|-<br />
| string || tolowercase || string;tolowercase;stringValue || stringVariable || Converts the passed string to lower case and assigns to the passed variable name. <br />
|-<br />
| string || touppercase || string || stringVariable || Converts the passed string to upper case and assigns to the passed variable name. <br />
|-<br />
| 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. <br />
|-<br />
| 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.<br />
|-<br />
| 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'''.<br />
|-<br />
| turnorder || clear || none || none || Clears all entries from the {{Turn Tracker}}/Initiative<br />
|-<br />
| turnorder || addtoken || tokenid;trackervalue || none || Adds the token represented by "tokenid" to the initiative tracker with an initiavie value of "trackervalue"<br />
|-<br />
| turnorder || replacetoken || tokenid;trackervalue || none || Replaces the token represented by "tokenid" in the initiative tracker with an initiavie value of "trackervalue". Will add the token if it doesn't exist in the tracker.<br />
|-<br />
| turnorder || removetoken || tokenid || none || Removes the token represented by "tokenid" from the initiative tracker if it exists<br />
|-<br />
| turnorder || addcustom || textlabel;trackervalue || none || Add a custom text entry to the {{Turn Tracker}}/Initiative named "textlabel" with an initiative value of "trackervalue"<br />
|-<br />
| system || date || getdatetime || stringVariable || Returns the date time in the active timezone (see settings) <br />
|-<br />
| system || date || getdate || stringVariable || Returns the date in the active timezone (see settings) <br />
|-<br />
| system || date || gettime || stringVariable || Returns the time in the active timezone (see settings)<br />
|-<br />
| system || dumpvariables || "rolls", "string", or "array" || none || Dumps all of the defined variables of the indicated type to the console log<br />
|-<br />
| system || findability || system;findability;charactername;abilityname || stringVariable || Returns the object ID of the ability on the indicated character or "AbilityNotFound"<br />
|-<br />
|}<br />
<br />
Examples:<br />
<br />
<pre><br />
--~HowFarAway|distance;@{selected|token_id};@{target|token_id}<br />
</pre><br />
<br />
Returns the distance (Chebyshev) between the selected and target tokens and stores it in "HowFarAway".<br />
<br />
<pre><br />
--SelectedDudes|getselected<br />
</pre><br />
<br />
If 5 tokens were selected, 6 variables would be created: SelectedDudesCount (with a value of 5), SelectedDudes1, SelectedDudes2, SelectedDudes3, SelectedDudes4, SelectedDudes5.<br />
<br />
=== Information Request (--i) ===<br />
<br />
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.<br />
<br />
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.<br />
<br />
After the user has clicked the button and responded to the requests, ScriptCards will resume processing the script from where it left off.<br />
<br />
Here is an example “i” line:<br />
<br />
<pre><br />
--IScriptCards needs additional information to continue;Click to select a target and provide information|t;MyNewTarget;Missile1Target||q;MyNameIs;What is your name?<br />
</pre><br />
<br />
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.<br />
<br />
Supported information request types are “t” for target token, and “q” for query.<br />
<br />
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).<br />
<br />
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:<br />
<br />
<pre><br />
q;UserName;What is your name?|Fred|Bob|Sally|Nancy<br />
</pre><br />
<br />
Would have a dropdown menu with four choices.<br />
<br />
== Inline Formatting ==<br />
<br />
Inline formatting is processed on Direct Output lines only (--+ lines) and the following inline format markup is available:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Formatting Tags !! Description<br />
|-<br />
| [b]..[/b] || Bold the text between the markers <br />
|-<br />
| [i]..[/i] || Italicize the text between the markers <br />
|-<br />
| [u]..[/u] || Underline the text between the markers <br />
|-<br />
| [s]..[/s] || Strike-Thru the text between the markers <br />
|-<br />
| [c]..[/c] || Center alignment <br />
|-<br />
| [l]..[/l] || Left alignment <br />
|-<br />
| [r]..[/r] || Right alignment <br />
|-<br />
| [j]..[/j] || Full justification alignment <br />
|-<br />
| [#xxx]..[/#] or [#xxxxxx]..[/#] || Use a 3 or 6 digit hex code to colorize the text between the markers <br />
|-<br />
| [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, <code>[img width=128 height=128]</code> )<br />
|-<br />
| [button]caption::action[/button] || Create a button with the label "caption" that performs the action defined by "action". <br />
|-<br />
| [t] || Converted to HTML table tag. Text after the "t" will be included inside the tag (width, border, etc)<br />
|-<br />
| [/t] || Converted to HTML close table tag.<br />
|-<br />
| [tr] || Converted to HTML table row tag. Text after the "tr" will be included inside the tag<br />
|-<br />
| [/tr] || Converted to HTML close table row tag.<br />
|-<br />
| [td] || Converted to HTML table cell tag. Text after the "tr" will be included inside the tag<br />
|-<br />
| [/td] || Converted to HTML close table cell tag.<br />
|}<br />
<br />
== Variables ==<br />
<br />
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. While it is possible to assign both a string and a roll variable the same name, doing so will likely result in confusion when looking at the script later, so it is not recommended.<br />
<br />
String Variables are assigned with the --& statement and are referenced using [&variableName] notation.<br />
<br />
Roll Variables are assigned with the --= statement, and the assignment value is always processed by the ScriptCards Roll Processor (resolves dice rolls, etc.)<br />
<br />
There are a handful of variables assigned automatically when a ScriptCard is executed. These are all string variables, and are:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Variable !! Value<br />
|-<br />
| SendingPlayerID || Contains the object ID of the player that sent the macro<br />
|-<br />
| SendingPlayerName || Contains the display name of the player<br />
|-<br />
| SendingPlayerColor || Contains the color code associated with the player<br />
|-<br />
| SendingPlayerSpeakingAs || The contents of the "Speaking As" dropdown window<br />
|-<br />
| SendingPlayerIsGM || Contains 1 if the player is a GM, and 0 if the player is NOT a GM<br />
|}<br />
<br />
== Arrays ==<br />
<br />
Arrays are a special type of variable, and are managed by the function (<nowiki>--~</nowiki> command). All of the array function commands follow the same pattern:<br />
<br />
<pre>--~variableName|array;subcommand;arrayname;param1;param2;param3;...</pre><br />
<br />
Not all array commands return anything to "variableName". The function table above will specify the return type of the command if any.<br />
<br />
There are a couple of different ways to create an array:<br />
<br />
The '''define''' array subcommand creates (or recreates) an array and assigns it values - one for each included parameter after the array name. For example:<br />
<br />
<pre>--~|array;define;Fruits;mango;peach;strawberry;apricot;banana;apple</pre><br />
<br />
will create an array called '''Fruits''' with 6 elements in the order listed in the command (mango, peach, etc.)<br />
<br />
You can also use two other subcommands to create arrays based on tokens:<br />
<br />
<pre>--~Count|array;pagetokens;Everybondy;@{selected|token_id}</pre><br />
<br />
and<br />
<br />
<pre>--~Count|array;selectedtokens;Selected</pre><br />
<br />
In both cases, arrays of tokens will be created, and a string variable called "Count" will be set to the number of tokens in the array. The '''pagetokens''' command returns (by default) all of the tokens on the page that contains the token passed as the parameter after the array name. You can filter the tokens that "pagetokens" includes in the array by appending an optional parameter describing the type of token you are looking for:<br />
<br />
<pre>--~Count|array;pagetokens;Everybondy;@{selected|token_id};npc</pre><br />
<br />
Will return only tokens on the page that represent characters that do not have a ''controlledby'' parameter set. The available options are "all" (default), "char", "graphic", "pc", and "npc".<br />
<br />
The '''selectedtokens''' command returns an array with all of the tokens that were selected when the script was called.<br />
<br />
You can also use an arbitrary string to create an array, specifying a delimiter with the '''fromstring''' command:<br />
<br />
<pre><br />
--&names|Fred<br />
--&names|+,Sally<br />
--&names|+,Ted<br />
--&names|+,Joyce<br />
--~|array;fromstring;,;[&names]<br />
</pre><br />
<br />
The above example builds a comma-separated string and then uses "fromstring" to create an array with 4 elements from it, specifying the comma as the delimiter.<br />
<br />
Finally, you can use the '''statusmarkers''' command to create an array with one entry for each active status marker on a specified token:<br />
<br />
<pre>--~|array;statusmarkers;Conditions;@{selected|token_id}</pre><br />
<br />
will create an array with one entry for each status active on the selected token. The array elements will be the internal name of the status (if you are using custom status marker packs, the names will be specified in the marker pack).<br />
<br />
'''Traversing Arrays'''<br />
<br />
Each array keeps track of an internal index position (starting at 0). Several commands let you manage this index:<br />
<br />
*'''getindex''' returns the current index value<br />
*'''setindex''' sets the index to the specified location in the array<br />
*'''getlength''' returns the number of elements in the array<br />
*'''indexof''' returns the index location of the specified element<br />
<br />
Other commands let you retrieve values from the array:<br />
<br />
*'''getfirst''' sets the index to 0 and returns the value at that position<br />
*'''getnext''' advances the index by 1 and returns the new current value<br />
*'''getprevious''' reduces the index by 1 and returns the new current value<br />
*'''getlast''' sets the index to the last elements in the array and returns the new current value<br />
<br />
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.<br />
<br />
'''Manipulating Array Elements'''<br />
<br />
Several array commands deal with inserting, removing, and modifying elements:<br />
<br />
*'''add''' works just like define, except that it takes an existing array and adds elements to it based on the passed parameters<br />
*'''remove''' looks for items matching each passed parameter and removes them from the indicated array if they exist<br />
*'''removeat''' allows you to specify an index location in the array and remove the element at that position<br />
*'''replace''' searches an array for a value and replaces all occurrences of it with a new value (if found)<br />
*'''sort''' sorts the elements in the array in ascending order<br />
*'''strinfigy''' returns a string variable that includes each array element separated by semicolons (;) <br />
<br />
'''Referencing Array Elements'''<br />
<br />
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.<br />
<br />
<pre><br />
!script {{<br />
--~dummy|array;pagetokens;myarray;@{selected|token_id}<br />
--~count|array;getcount;myarray<br />
--+Total:|There are [&count] graphical objects on the page<br />
--~testvar|array;getfirst;myarray<br />
--:loop|<br />
--+Value|[*[&testvar]:character_name]<br />
--~testvar|array;getnext;myarray<br />
--?[&testvar] -ne ArrayError|loop<br />
--+Loop1|Is Done!<br />
}}<br />
</pre><br />
<br />
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:<br />
<br />
<pre><br />
!script {{<br />
--~dummy|array;pagetokens;myarray;@{selected|token_id}<br />
--~count|array;getcount;myarray<br />
--+Total:|There are [&count] graphical objects on the page<br />
--%loopCounter|1;[&count]<br />
--+Value|[*[@myarray([&loopCounter])]:character_name]<br />
--%|<br />
--+Loop|Is Done!<br />
}}<br />
</pre><br />
<br />
This line : <nowiki>--+Value|[*[@myarray([&loopCounter])]:character_name]</nowiki> uses [@arrayName(index)] format (inside a [*characterid:attribute] syntax) to perform the same task as running through the loop with the index.<br />
<br />
(Note: Additional examples are on the way...)<br />
<br />
== For...Next Loops ==<br />
<br />
For...Next loops in ScriptCards are supported with the with the --% statement type. A loop is defined by starting off with:<br />
<br />
<pre><br />
--%LoopCounter|<start>;<end>;[step]<br />
</pre><br />
<br />
The start and end values are required, while the step parameter is optional. If the step is omitted, it will be assumed to be 1. A string variable named after the line tag ("LoopCounter" in the case above) will be created and will hold the current iteration value for the loop. Here is a real example:<br />
<br />
<pre><br />
--%LoopCounter|1;10;1<br />
</pre><br />
<br />
This will begin a loop identified by "LoopCounter" that will start at 1, increasing by 1 each iteration (the step) until it has completed 10 executions.<br />
<br />
The "next" statement is simply <code>--%|</code>, with no tag or parameters. This indicates to ScriptCards that it should increment the counter and go back to the beginning of the loop. Extending the example above:<br />
<br />
<pre><br />
!script {{<br />
--%LoopCounter|1;10;1<br />
--=Roll|1d20<br />
--+Loop|Counter is [&LoopCounter], roll was [$Roll]<br />
--%|<br />
}}<br />
</pre><br />
<br />
The <code>--%!|</code> sequence will break out of the loop, no matter how many iterations are remaining.<br />
<br />
The % and %! character sequences can also be used as part of a 1.2.1+ non-branching conditional to continue or break the loop:<br />
<br />
<pre><br />
--?"X[&RollInto]X" -eq "XX"|%<br />
</pre><br />
<br />
In this example, if the string variable RollInfo is empty, the loop will return to the top and continue with the next iteration, while:<br />
<br />
<pre><br />
--?"X[&RollInto]X" -eq "XX"|%!<br />
</pre><br />
<br />
Would cause the whole loop to end if the condition were true.<br />
<br />
== Referencing ==<br />
<br />
=== Roll Variables===<br />
<br />
Roll Variables can be referenced from the content portion of any line type, and from the tag portion of conditional statements. The referenced value is replaced when the line is executed.<br />
<br />
There are several modifiers that can be used to reference parts of a roll:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Modifier !! Meaning<br />
|-<br />
| No modifier || In a Direct Output Line (<nowiki>--+</nowiki>), GM Output Line (<nowiki>--*</nowiki>), or String Assignement (<nowiki>--&</nowiki>), 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<br />
|-<br />
| .Total || The end result of the roll equation. Formatting rules for "No Modifier" apply based on line type. <br />
|-<br />
| .Raw || The total value of the roll variable without any formatting, no matter what kind of line the reference is used in.<br />
|-<br />
| .Base || The cumulative result of any dice rolled in the Roll Text (Numeric modifiers are not included) <br />
|-<br />
| .Ones || The number of dice in the roll that came up as 1s <br />
|-<br />
| .Aces || The number of dice in the roll that came up as the maximum number on the die <br />
|-<br />
| .Odds || The number of dice in the roll that came up with an odd number <br />
|-<br />
| .Evens || The number of dice in the roll that came up with an even number <br />
|-<br />
| .RollText || The raw text of the roll that was use to generate the results <br />
|-<br />
| .Text || A text representation of the results of the roll, including the numbers rolled for each die <br />
|-<br />
| .tableEntryText || The text portion of the result of a table roll<br />
|-<br />
| .tableEntryImgURL || The image source portion of the result of a table roll<br />
|-<br />
| .tableEntryValue || If the tableEntryText is purely numeric, will contain the numeric value<br />
|}<br />
<br />
=== String Variables ===<br />
<br />
To reference a string variable, use the notation [&variablename]. String variables can be referenced in direct output, roll variable assignment, and string variable assignment statements.<br />
<br />
=== Character/Token Attributes ===<br />
<br />
A character or token attribute can be referenced from content portion of any type of line and is substituted when the line is executed. The general format for referencing a character attribute is [*ID:attribute]. ID can be a token ID or a character ID (these start with a dash). Additionally if you have specified a sourceToken or targetToken, you can substitute "S" or "T" for the ID (for example [*S:npc_type] will retrieve the npc_type attribute from the source token.<br />
<br />
By default, all attribute references will be pulled from the '''''character''''' object that the ID represents (either directly or by being a Token ID that represents a character).<br />
<br />
Keep in mind, that if you want to access the "max" of a character attribute (for example, the max hit points), then you cannot trust the name that your roll20 character sheet shows you when you hover your mouse over the max hit points. For example, this reference will not work: [*S:hp_max]. Instead, you need to use this reference: [*S:hp^].<br />
<br />
If your ID refers to a token, token attributes can be accessed by preceding the attribute name with "t-", for example [*S:t-aura1_radius]. Supported token attributes are:<br />
<br />
{|<br />
| t-name || t-id || t-statusmarkers || t-bar1_value<br />
|-<br />
| t-bar1_max || t-bar2_value || t-bar2_max || t-bar3_value<br />
|-<br />
| t-bar3_max || t-top || t-left || t-width<br />
|-<br />
| t-height || t-rotation || t-layer || t-aura1_radius<br />
|-<br />
| t-aura1_color || t-aura2_radius || t-aura2_color || t-aura1_square<br />
|-<br />
| t-aura2_square || t-tint_color || t-light_radius || t-light_dimradius<br />
|-<br />
| t-light_angle || t-light_losangle || t-light_multiplier || t-light_otherplayers<br />
|-<br />
| t-light_hassight || t-flipv || t-fliph || t-controlledby<br />
|-<br />
| t-_cardid || t-_pageid || t-imgsrc || t-bar1_link<br />
|-<br />
| t-bar2_link || t-bar3_link || t-represents || t-layer<br />
|-<br />
| t-isdrawing || t-name || t-gmnotes || t-showname<br />
|-<br />
| t-showplayers_name || t-showplayers_bar1 || t-showplayers_bar2 || t-showplayers_bar3<br />
|-<br />
| t-showplayers_aura1 || t-showplayers_aura2 || t-playersedit_name || t-playersedit_bar1<br />
|-<br />
| t-playersedit_bar2 || t-playersedit_bar3 || t-playersedit_aura1 || t-playersedit_aura2<br />
|-<br />
| t-lastmove || t-adv_fow_view_distance || t-has_bright_light_vision || t-has_night_vision<br />
|-<br />
| t-night_vision_distance || t-emits_bright_light || t-bright_light_distance || t-emits_low_light<br />
|-<br />
| t-low_light_distance || t-has_limit_field_of_vision || t-limit_field_of_vision_center || t-limit_field_of_vision_total<br />
|-<br />
| t-has_limit_field_of_night_vision || t-limit_field_of_night_vision_center || t-limit_field_of_night_vision_total || t-has_directional_bright_light<br />
|-<br />
| t-directional_bright_light_center || t-directional_bright_light_total || t-has_directional_dim_light || t-directional_dim_light_center<br />
|-<br />
| t-directional_dim_light_total || t-lightColor || || |<br />
|}<br />
<br />
'''''It is important to note that some attributes names on tokens have corresponding attribute names on characters, which represent different values. For example, [*T:id] returns the character ID, while [*T:t-id] returns the token ID.'''''<br />
<br />
=== Subroutine Parameters ===<br />
<br />
When using a gosub statement (-->) or a conditional marked as a gosub (prefixing the label with a > character), you can pass any number of parameters separated by semicolons (;) that the code in the subroutine can utilize.<br />
<br />
Subroutine parameters are numbered starting at 1, and are accessed by using the notation [%number%], so the first parameter is [%1%], the second is [%2%], etc.<br />
<br />
Parameter substitution happens on all line types, and happens prior to character attribute references or roll variable substitution.<br />
<br />
=== Campaign Attribute ===<br />
You can retrieve properties of the API's Campaign object with the [*C:attributename] syntax. For example, [*C:playerpageid] will retrieve the current player ribbon page from the Campaign object.<br />
<br />
=== Page Attributes ===<br />
If you have set the '''activepage''' parameter, you can retrieve page-related properties with the [*P:attributename] syntax, including the page's UDL parameters.<br />
<br />
=== Repeating Section Values ===<br />
<br />
You can reference repeating attribute data using the syntax [*R:attributename] syntax (similar to referencing standard character attributes). The currently active repeating row information will be used to retrieve attribute values. You can also retrieve the full attribute name for a repeating row attribute by using the [*R>attributename] notation. This is useful to pass to things like chatsetattr.<br />
<br />
See the section named [[#Repeating Section Access (--R)|Repeating Section Access]] for more information.<br />
<br />
=== Array Elements ===<br />
After an array has been declared, the elements can be referenced with [@arrayName(index)]. Array indices start at 0.<br />
<br />
== Deferred Resolution for Meta Scripts ==<br />
<br />
As of 1.2.9, ScriptCards supports a deferral character for use when calling another API script with via the --@ statement, to defer processing of meta script references so they get processed prior to the sub-API call insted of prior to ScriptCards execution. To defer this processing for meta script (SelectManager, Fetch) by inserting a deferral character into the meta call. For example, if I want to have ScriptCards call TokenMod as if the token for "Quej Gr'stra" (yes, I let Roll20 name my test NPCs) I could use something like this:<br />
<br />
--@token-mod|{^& select Quej Gr'stra} _on showname<br />
<br />
The "^" in between { and & will prevent SelectManager from seeing the call when the ScriptCard script is processed, but the --@ statement will remove the deferral character so the command that will be sent by ScriptCards is:<br />
<br />
!token-mod {& select Quej Gr'stra} --on showname<br />
<br />
With the deferral character removed, SelectManager will see the {& select ...} and do its magic.<br />
<br />
While the default deferral character is "^", the deferral character is a setting that can be changed:<br />
<br />
--#deferralcharacter|%<br />
<br />
Will make % the deferral character for future --@ statements in the running script.<br />
<br />
There are currently three supported Meta script structures: {^&...} for SelectManager, @^(...) and *^(...) for fetch, where the ^ in the structures here represents the placement of the deferral character.<br />
<br />
== Arrays ==<br />
<br />
Arrays are a new data type introduced in version 1.1.12 of ScriptCards, and are manipulated with associated function (--~) commands.<br />
<br />
* Arrays are a lists of strings. Items in an array cannot contain the semi-colon (;) character, as that is used to separate parameters in the function code that deals with arrays.<br />
* Arrays are accessed via the --~ script command. In some cases, the value of the tag (variable name) for array commands is not used, and can be a dummy value or simply omitted. I have omitted them in the statements below.<br />
* All commands that DO return a value return string values, even if the content is numeric.<br />
* If a command returns a value and there is some sort of reason that it isn't an array value, you will get "ArrayError" in the return value. This can happen if you reach the end of an array while stepping through it, for example, so checking for "ArrayError" can serve as the end condition for a loop.<br />
* Each array keeps track of its current index, allowing you to step forward and backwards through arrays.<br />
* Any number of arrays can be defined.<br />
* Unlike string variables and roll variables, array variables cannot (currently) be referenced directly. It is necessary to use the function (--~) syntax to manipulate arrays and get values from them as strings for use in other parts of your script.<br />
<br />
<br />
== Reentrant Scripts ==<br />
<br />
Reentrant scripts allow you to create buttons in your script code that will re-execute the script at a given label within the code. If you set the reentrant setting (--#reentrant|somevalue) to a non-zero value, your setting and variable information will be preserved between executions. Reentrant script can be used to present menus or choices and then continue acting.<br />
<br />
Reentrant buttons are created with the [rbutton]Caption::ReentryLabel;Parameter[/rbutton] construct. The caption will be displayed on the generated button. ReentryLabel is the name of a label in your script that the button will jump to when clicked, and Parameter will be passed in as a string value called "reentryval".<br />
<br />
Example:<br />
<pre><br />
!script {{<br />
--#reentrant|testing<br />
--=Roll|1d20<br />
--+Roll|[$Roll]<br />
--&String|That was a [$Roll.Raw]!<br />
--~x|array;define;MyArray;Apple;Banana;Orange<br />
--+Try it|[rbutton]Hello!::EXEC_PC_SPELL;9[/rbutton]<br />
--X|<br />
<br />
--:EXEC_PC_SPELL|<br />
--+ReentryVal|[&reentryval]<br />
--+The value of Roll is|[$Roll]<br />
--+Value of String|[&String]<br />
--+Array|[@MyArray(0)]<br />
--X|<br />
}}<br />
</pre><br />
<br />
This script sets up some variables and then displays a button labeled "Hello!". If the user clicks the button, the script will be re-entered starting at the "EXEC_PC_SPELL", which will display the content of the variables from the original execution.<br />
<br />
'''''Note: This section needs to be expanded upon'''''<br />
<br />
== Procedure Libraries ==<br />
<br />
You can now create handouts in your game in Roll 20 with the name format "ScriptCards Library NAME", where name is a name you assign to the library. Library names are case sensitive. It is my hope that the more proficient ScriptCards scripters out there will provide procedure libraries (or procedures that can be included in libraries) for others to use to make their scripting life easier. Be they specific to a game system, or to a type of activity, I think a robust set of libraries that GMs could use to enhance their scripting capabilities would be very valuable to the community. Should such things begin to emerge, I’ll create a portion of the ScriptCards Wiki page to house them.<br />
<br />
To include one or more libraries in a script, use the +++libname+++ directive (does not need a -- line associated with it). Multiple library names can be specified by separating them with semicolons (i.e., +++General;dnd5elib;Colorize+++ would include three libraries (General, dnd5elib, and Colorize).<br />
<br />
Included libraries are separated from the main script code by the automatic inclusion of "--X|" before the first library is appended to the script, and all libraries are loaded at the end of the script before script processing takes place.<br />
<br />
Procedures and labels in libraries can be used just as if they were included in the body of your script. Note that this DOES mean that you could, technically, jump into a library with a direct branch (--^) or direct branch conditional, but I recommend using libraries to store reusable procedures.<br />
The Notes section of the library handout stores the library code, and is written just like any other ScriptCards code except:<br />
<br />
* They cannot use roll queries (?{Some Prompt:}) to get information from the user at execution time.<br />
* They cannot use @{} notation to access character and token information.<br />
<br />
Both of these limitation stem from the fact that Procedure Libraries are not processed by the chat server, which is what handles these items.<br />
<br />
Here is an example of handling damage modifications (resistance, vulnerability, and immunity) in D&D 5E with a library:<br />
<br />
<pre><br />
!script {{<br />
+++dnd5elib+++<br />
--#|Damage Modifiers Test<br />
--#targettoken|@{target|token_id}<br />
-->Lib5E_CheckDamageModifiers|ResistType;fire<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] fire damage<br />
<br />
-->Lib5E_CheckDamageModifiers|ResistType;cold<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] cold damage<br />
<br />
-->Lib5E_CheckDamageModifiers|ResistType;poison<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] poison damage<br />
<br />
-->Lib5E_CheckDamageModifiers|ResistType;acid<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] acid damage<br />
<br />
--X|<br />
}}<br />
</pre><br />
<br />
Library content (In a handout called “ScriptCards Library dnd5elib” NOTE: Paste into Notepad first and then paste into the handout in Roll20 to avoid bringing over HTML formatting from the web site):<br />
<br />
<pre><br />
--/|ScriptCards Library: dnd5elib version 0.0.1<br />
--/|Provides various utility procedures for D&D 5E games<br />
<br />
--/|Lib5E_CheckDamageModifiers handle damage resistance, vulnerability, and immunity. <br />
--/|Pass a string variable to be filled with a string to be appended to a dice roll and the damage type <br />
<br />
--:Lib5E_CheckDamageModifiers|damageVariableName;damageType<br />
--&[%1%]|<br />
--?"[*T:npc_vulnerabilities]" -inc "[%2%]"|>_Lib5E_IsVulnerable;[%1%]<br />
--?"[*T:npc_resistances]" -inc "[%2%]"|>_Lib5E_IsResistant;[%1%]<br />
--?"[*T:npc_immunities]" -inc "[%2%]"|>_Lib5E_IsImmune;[%1%]<br />
--<|<br />
<br />
--:_Lib5E_IsVulnerable| --&[%1%]| * 2 [Vulnerable] --<|<br />
--:_Lib5E_IsResistant| --&[%1%]| \ 2 [Resistant] --<|<br />
--:_Lib5E_IsImmune| --&[%1%]| * 0 [Immune] --<|<br />
</pre><br />
<br />
The idea is that the functions in the library create a string that can be appended to a roll to modify the output based on resistances, so you pass Lib5E_CheckDamageModifiers the name of the string variable you want to use and the damage type. The variable (ResistType in this case) will include either nothing, “* 2 [Vulnerable]”, “\ 2 [Resistant]”, or “* 0 [Immune]” which can be included in a roll assignment (--=) to modify the damage as appropriate. The order here might be important if an NPC is misconfigured to be both resistant and immune to the same damage type. Since immune is an absolute, having it last ensures that it will override resistant or vulnerable. A creature that is both vulnerable and resistant (again, misconfigured) will come back as resistant since that condition is checked after vulnerable.<br />
Some notes: I prefix my library labels with either “Lib5E_” or “_Lib5E_” as a clarity convention. This isn’t strictly necessary but you should be aware that if two libraries (or if your script and a library) define the same label, the last label defined will win. Since libraries are appended to the end of the script in the order you include them in the +++libname+++ directive, you can somewhat control this, but it is probably best to avoid re-declaring labels. <br />
<br />
In my case, items beginning with “Lib5E_” are intended to be called by scripts, while items beginning with “_Lib5E_” are intended to be used as subroutines by the “public” procedures. Of course, there is no reason you couldn’t call them directly.<br />
<br />
You might also note that I’ve included some library information in comment lines (--/|) at the top of the library. These are ignored by ScriptCards, and are a good way to convey requirements, parameters, usage information, etc.<br />
<br />
== Example Libraries ==<br />
<br />
=== dnd5elib ===<br />
<br />
[https://github.com/kjaegers/ScriptCards Download the dnd5elib Library from the ScriptCards GitHub]<br />
<br />
The '''dnd5elib''' library provides a collection of utility procedures that help simplify dealing with the D&D 5E Official Sheet. Some of the procedures in this library require '''chatsetattr''' to be installed in your game. This is a growing library, and currently only has a handful of routines. They are:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Procedure Name !! Notes<br />
|-<br />
| style="white-space:nowrap" | Lib5E_CheckDamageModifiers || This procedure can be used to evaluate vulnerabilities, resistances, and invulnerabilities on an NPC. After setting the --#target| parameters, pass the Lib5E_CheckDamageModifiers procedure a variable name (no reference information) and a damage type (i.e., fire, cold, bludgeoning, etc.), and the procedure will then create a string variable with with a name equal to the first parameter that you passed into the procedure. This variable will contain a string that can be included in a roll line (--=), in order to modify the roll as appropriate. For example, '''-->Lib5E_CheckDamageModifiers|ResistType;fire''' will check the current target character's attributes for "fire" and will either return an empty string (no references), "* 0 [Immune]" if the creature is immune, "\ 2 [Resistant]" if the creature is resistant, or "* 2 [Vulnerable]" if the creature is vulnerable to fire damage.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_DeductSpellSlot || Pass in a character_id and a slot level, and the script will expend one spell slot of that level, capping the value at 0 slots remaining. For Example '''<nowiki>-->Lib5E_DeductSpellSlot|@{selected|character_id};1</nowiki>''' to deduct a first level spell slot from the selected character.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_FindResource || Used to locate a resource value on a character. Pass in a character_id, a resource name, and two variable names. The procedure will check both repeating and non-repeating resources looking for a resource whose name matches what was passed in and return three variables. The first will be a string variable named for the 3rd parameter and contains the attribute name of the resource's "name" field. The second will be a string variable named after parameter 4 and contains the resource's value field attribute name, and the third variable is a Roll Variable, also named after the 4th parameter that contains the current resource value. Example: '''<nowiki>-->Lib5E_FindResource|@{selected|character_id};Crossbow bolts;ResName;ResValue</nowiki>''' will find "Crossbow bolts" as a resource on the character and return [&ResName] which is the name of the resource attribute, [&ResValue] which is the '''name of the attribute that stores the value''' and [$ResValue] which is the current numeric value of the resource.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Global_Attack_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Attack Modifiers (repeating_tohitmod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Bless" for 1d4 active and "Being Cool" for +2 active, I will get a return string " + 1d4 [Bless] + 2 [Being Cool]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Save_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Save Modifiers (repeating_savemod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Bless" for 1d4 active and "Being Cool" for +2 active, I will get a return string " + 1d4 [Bless] + 2 [Being Cool]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Skill_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Skill Modifiers (repeating_skillmod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Guidance" for 1d4 active and "Being Cool" for +2 active, I will get a return string " + 1d4 [Guidance] + 2 [Being Cool]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_AC_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Save Modifiers (repeating_savemod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Shield of Faith" with a value of 2 active, I will get a return string " + 2 [Shield of Faith]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Damage_Modifiers || Pass a character ID and TWO string variable to set the return value. The first string will be for normal damage, and the second will be the additional damage on a crit. This procedure will look through the Global Damage Modifiers (repeating_damagemod_*) for rows that are active (checked on the character sheet) and return two strings with the dice rolls and descriptions for them (for example, if I have "Sneak Attack" with a value of 1d6 normal and 1d6 critical damage active, I will get a return string " + 1d6 [Sneak Attack]" and another string of " + 1d6 [Sneak Attack CRIT]" that can be used in a dice rolls.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_DivineSmiteDice || Used to calculate the number of dice to be rolled for a paladin's Divine Smite. Pass a target token id, a spell slot level, and a string variable to be set to the dice roll amount based on the NPC_TYPE attribute of the target token. The returned variable will contain a dice roll (like "3d8" that can be used in a --= line)<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Character_Summary || Pass a character ID to outputs a mini character sheet, including clickable buttons for attacks, actions, legendary actions, etc. Will automatically detect a PC vs NPC and output the appropriate sections.<br />
|}<br />
<br />
Due to formatting issues with the Wiki, the library code has been moved to a [https://gist.github.com/kjaegers/52f6049ddd257f0a1288aca4bbde13c5 GITHUB GIT]. Please view the GIST in raw mode and copy the text and paste it into a handout called "ScriptCards Library dnd5elib" in your Roll20 Game.<br />
<br />
== What to Know if you are Coming from PowerCards ==<br />
<br />
''Note: This section is a work in progress.''<br />
<br />
While ScriptCards and PowerCard have very similar output goals, their internals and use are quite different. The table below summarizes some of the major differences between the scripts.<br />
<br />
::{| class="wikitable"<br />
|-<br />
! PowerCards !! ScriptCards <br />
|-<br />
| With a handful of exceptions, all lines in a PowerCard macro are intended to produce a line of output on the final card. || With ScriptCards, ONLY the <code>--+</code> and <code>--*</code> statement types produces output <br />
|-<br />
| PowerCards lines begin with two dashes (<code>--</code>) followed by a unique tag name for the line, followed by a vertical bar and the content for the line. || ScriptCards lines begin with two dashes (<code>--</code>) followed by a '''statement type identifier''', which is a single character that identifies the type of line to the interpreter. This is followed by a tag (frequently optional), a vertical bar, and the parameters for the statement being executed.<br />
|-<br />
| PowerCard macros are always processed top to bottom. Lines can be hidden so they don't output anything, but there is no looping or branching (--SkipTo looks like a branch, but it just hides all of the lines until the referenced label. || ScriptCards scripts support true branching, including direct branching (<code>--^</code>) and procedure branching (<code>--></code>) and (<code>--<</code>). Procedures support parameters and a call stack so procedures can be nested to call other procedures.<br />
|-<br />
| All lines in a PowerCards macro need to have unique tags because PowerCards builds the card as a single JavaScript object using the tag names to store what will be displayed. This is why repeated tag names always result in the last one being shown. || ScriptCards tags do not need to be unique, and in the case of many line types are optional.<br />
|-<br />
| PowerCards conditionals result in either showing or hiding the line they are on. || ScriptCards conditionals '''''only''''' support branching as the result of the comparison. This branching can be direct (a GOTO) or procedural (a GOSUB) '''''NOTE: As of version 1.2.0, ScriptCards also supports roll/string variable assignment as a result of conditional evaluation'''''<br />
|-<br />
| PowerCards relies on the Roll20 [[Quantum Roll]] server and inline rolls for all dice functions || ScriptCards includes its own dice roll parser, and '''''does not support''''' inline rolls.<br />
|-<br />
| PowerCards RollIDs (often mistaken for variables) are assigned by analyzing the results of an inline roll, and cannot be referenced in other rolls, so you can't roll a <code>1d4</code> and then roll a <code>1d20</code> and add the <code>1d4</code> result because all of the rolls happen on the chat server before PowerCards gets the macro text. || ScriptCards supports two types of variables: Roll Variables and String Variables. Because ScriptCards uses its own roll parser and is not dependent upon the chat server, rolls and their results can be used in other rolls, math functions, output, etc.<br />
|}<br />
<br />
== Example Scripts ==<br />
<br />
Below are some sample scripts that utilize the various statement types in ScriptCards:<br />
<br />
=== Divine Smite ===<br />
<br />
This script will prompt the user for a spell slot level to expend on a divine smite. It will check the target's npc_type to see if it is an Undead or Fiend, which adds an additional d8 to the smite roll.<br />
<br />
[[File:ScriptCards Divine Smite.png|Divine Smite Script Output]]<br />
<br />
<pre><br />
!scriptcard {{<br />
--#title|Divine Smite<br />
--=DiceCount|?{Spell Slot Level?|1|2|3|4|5|6|7|8|9} + 1<br />
--=IsFiendOrUndead|0<br />
--?"@{target|npc_type}" -inc fiend|>IsBoosted<br />
--?"@{target|npc_type}" -inc undead|>IsBoosted<br />
--=TotalDice|[$DiceCount] + [$IsFiendOrUndead]<br />
--=SmiteRoll|[$TotalDice]d8<br />
--#emoteText|@{selected|token_name} smites @{target|token_name}<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
--+Smite|deals [$SmiteRoll] radiant damage.<br />
--X|<br />
<br />
--:IsBoosted|<br />
--=IsFiendOrUndead|1<br />
--<|<br />
}}<br />
</pre><br />
<br />
==== How It Works ====<br />
<br />
The first line sets the "title" card parameter to "Divine Smite".<br />
<br />
Line 2 Shows a query to the user asking for the spell slot level, adds one and stores the value in the "DiceCount" Roll Variable. The query/dropdown is generated by the chat server prior to the script being executed.<br />
<br />
Line 3 defaults the "IsFiendOrUndead" Roll Variable to 0.<br />
<br />
Lines 4 and 5 compare the target's "npc_type" attribute (passed by the chat server as text) to see if they include either "undead" or "fiend". If true, the IsBoosted subroutine will be called. No parameters are passed to this subroutine.<br />
<br />
Line 6 sets the "TotalDice" variable to the base (DiceCount) number plus the IsFiendOrUndead number, which will be a 0 or a 1.<br />
<br />
Line 7 calculates "SmiteRoll" by rolling a number of d8 equal to the "TotalDice" value.<br />
<br />
Lines 8-10 set the parameters for the emote, which appears above the card content. By setting the sourceToken and the targetToken, their icons will appear in the emote surrounding the text describing the action.<br />
<br />
Line 11 is the only line that actually produces output on the card. It results in "Smite deals # radiant damage".<br />
<br />
Line 12 ends the script execution, preventing the script from continuing and running the subroutines out of context.<br />
<br />
Lines 14-16 are the IsBoosted subroutine, starting with the :IsBoosted label. The IsFiendOrUndead variable is set to 1, and a return from subroutine is executed.<br />
<br />
=== Magic Missile ===<br />
<br />
This script demonstrates using a loop and calling a subroutine to fire a number of missiles determine by the spell slot level used to cast the spell.<br />
<br />
[[File:ScriptCards_MagicMissile_Fixed.png|Magic Missile Script Output]]<br />
<br />
<pre><br />
!scriptcard {{ <br />
--#title|Magic Missile<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
--=MissileCount|?{Spell Slot Level?|1|2|3|4|5|6|7|8|9} + 2<br />
--=DisplayCount|1<br />
--=MissileDamage|0<br />
--#leftsub|Slot level ?{Spell Slot Level?}<br />
--#rightsub|Ranged Attack<br />
--#emoteText|Fred uses a level ?{Spell Slot Level?} spell slot to fire [$MissileCount.Total] missiles of magical force!<br />
--:MissileLoop|<br />
-->FireMissile|<br />
--=DisplayCount|[$DisplayCount] + 1<br />
--?[$DisplayCount] -le [$MissileCount]|MissileLoop<br />
--+Total|Total damage is [$MissileDamage]<br />
--X|<br />
<br />
--:FireMissile|<br />
--=ThisMissile|1d4 + 1<br />
--=MissileDamage|[$MissileDamage] + [$ThisMissile]<br />
--+Missile|[$DisplayCount.Total] Hits for [$ThisMissile] [b]force[/b] damage<br />
--<|<br />
}}<br />
</pre><br />
<br />
==== How It Works ====<br />
<br />
Lines 1-3 set the card title, the source token and the target token. Setting these tokens causes their icons/avatars to appear in the Emote section of the card.<br />
<br />
Line 4 asks the user what spell slot level they wish to use to cast magic missile. The number of missiles fired is equal to 2 plus the spell level, and this is stored in the MissileCount variable.<br />
<br />
Line 5 stores a 1 in the DisplayCount variable. This will be used to control the loop to determine the number of missiles fired and the missile number when displaying damage rolls.<br />
<br />
Line 6 initializes MissileDamage to 0<br />
<br />
Line 7 sets the left subtitle to the text "Slot Level #", where # is the spell slot level being used.<br />
<br />
Line 8 sets the right subtitle to the text "Ranged Attack".<br />
<br />
Line 9 sets the emoteText parameter with a description of the action, including the slot level and number of missiles fired.<br />
<br />
Line 10 is a label for the missile firing loop<br />
<br />
Line 11 Calls the "FireMissile" subroutine<br />
<br />
Line 12 increases the DisplayCount variable by 1<br />
<br />
Line 13 Checks to see if there are still missles to fire (DisplayCount <= MissileCount) and if so branches to MissileLoop<br />
<br />
Line 14 Displays the total damage dealt by the spell.<br />
<br />
Line 15 stops execution of the script to prevent out of context execution of the subroutine.<br />
<br />
Lines 76-21 are the FireMissile subroutine, beginning with the FireMissile label. The 1d4+1 is rolled and assigned to "ThisMissile". The result is added to the existing MissileDamage total, and a line for the current missile is displayed with the missile number and the damage for the missile.<br />
<br />
=== Longsword Attack ===<br />
<br />
This script demonstrates a standard 5E D&D melee weapon attack, including detection of misses, fumbles, hits, and critical hits. If installed, alterbars is used to decrement the target's BAR3 value by the damage dealt.<br />
<br />
[[File:ScriptCards Longsword.png|Longsword Script Output]]<br />
<br />
<pre><br />
!scriptcard {{<br />
--#title|Longsword<br />
--#leftsub|Melee Attack<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
--#emoteText|@{selected|token_name} attacks @{target|token_name}<br />
--=TargetAC|@{target|npc_ac}<br />
--?[$TargetAC.Total] -gt 0|DoneWithAC<br />
--=TargetAC|@{target|ac}<br />
--:DoneWithAC|<br />
--=AttackRoll|1d20 + @{selected|strength_mod} [STR] + @{selected|pb} [PROF]<br />
--+Attack|@{selected|token_name} rolls [$AttackRoll] vs AC [$TargetAC].<br />
--?[$AttackRoll.Base] -eq 20|Crit<br />
--?[$AttackRoll.Base] -eq 1|Fumble<br />
--?[$AttackRoll.Total] -ge [$TargetAC.Total]|Hit<br />
--+Miss|The attack missed.<br />
--^Final|<br />
<br />
--:Fumble|<br />
--+Fumble!|The attack went horribly wrong.<br />
--^Final|<br />
<br />
--:Hit|<br />
--=Damage|1d8 + @{selected|strength_mod} [STR]<br />
--+Hit!|The attack hit @{target|token_name} for [$Damage] slashing damage.<br />
--@alter|_target|@{target|token_id} _bar|3 _amount|-[$Damage]<br />
--^Final|<br />
<br />
--:Crit|<br />
--=Damage|1d8 + @{selected|strength_mod} [STR] + 1d8 [CRIT]<br />
--+Critical Hit!|The attack hit @{target|token_name} for [$Damage] slashing damage.<br />
--@alter|_target|@{target|token_id} _bar|3 _amount|-[$Damage]<br />
<br />
--:Final|<br />
}}<br />
</pre><br />
<br />
==== How it Works ====<br />
<br />
In lines 1-5, we set the title, subtitle, and emote text along with the tokens for the emote area.<br />
<br />
Lines 6-9 allow us to determine the AC of the target. On the 5E Roll20 sheet, NPCs armor class is stored in "npc_ac", while PCs armor class is in "ac". First we grab npc_ac and if it is zero, we check AC.<br />
<br />
Line 10 rolls the attack roll, rolling 1d20 and adding the attacker's strength modifier and proficiency bonus<br />
<br />
Line 11 displays the result of the attack roll on the card<br />
<br />
Lines 12-14 determine what kind of result the attack had. If the .Base value of the roll was 20, we branch to "Crit". If it was 1, we branch to "Fumble". If the .Total value of the roll was greater than or equal to the AC that was determined in Lines 6-9, we branch to Hit.<br />
<br />
Assuming we didn't branc anywhere, the result of the attack was a miss, so we display that on line 15 and then branch to "Final"<br />
<br />
This is followed by three branch segments, :Fumble, :Hit, and :Crit. A fumble displays a text message and branches to :Final.<br />
<br />
On a hit or a crit, we roll Damage (adding additional damage dice on a crit). We display a "Hit!" or "Critical Hit!" message and then make an API call to AlterBars, passing it the token id, bar we want to modify (3 in this case), and the amount we want to modify by the Damage value.<br />
<br />
=== Party Health Status ===<br />
<br />
This example calculates the current Hit Points remaining and HP percentage for each character and creates a color-coded display with the current party status.<br />
<br />
[[File:ScriptCards Party Health.png]]<br />
<br />
<pre><br />
!scriptcard {{<br />
--#title|Party Status<br />
--#titleCardBackground|#33CC33<br />
--#oddrowbackground|#bfee90<br />
--#evenrowbackground|#90eebf<br />
-->HealthCheck|@{Quej Grastra|character_id}<br />
-->HealthCheck|@{Brim Cheuto|character_id}<br />
-->HealthCheck|@{Odug Ututees|character_id}<br />
--X|End of card Execution<br />
<br />
--:HealthCheck|<br />
--=HealthPerc|[*[%1%]:hp] / [*[%1%]:hp^] * 100 \ 1<br />
--=HealthColor|000000<br />
--?[$HealthPerc.Total] -gt 50|HealthSkip<br />
--=HealthColor|FF0000<br />
--:HealthSkip|<br />
--+[*[%1%]:character_name]|has [#[$HealthColor.RollText]][*[%1%]:hp] of [*[%1%]:hp^][/#] HP [R]([$HealthPerc.Total]%)[/R]<br />
--<|End of HealthCheck<br />
}}<br />
</pre><br />
<br />
==== How it Works ====<br />
<br />
Lines 1-4, we set the card title, and set the title background and row background colors to shades of green.<br />
<br />
Lines 5-7 make gosub calls the the "HealthCheck" subroutine, passing in the character ID of each of the named characters (these are the names of the characters in my test game)<br />
<br />
Line 8 terminates the script execution.<br />
<br />
The remaining lines of the script are the HealthCheck subroutine, which works like this:<br />
<br />
Line 10 is the subroutine label (:HealthCheck)<br />
<br />
Line 11 uses the character id passed as a parameter and combines it with character attribute lookup *(...) to retrieve the value of "hp" and "hp<nowiki>^</nowiki>" for the character. The <nowiki>^</nowiki> character is used to specify that we want the MAX value for this attribute for the second call. We divide these two numbers and multiple by 100 to get a percentage. Finally, we use integer division by 1 to round the percentage and drop the decimals. The end result gets stored in the HealthPerc roll variable.<br />
<br />
Line 12 defaults to color of the health text to black<br />
<br />
Line 13 check to see if the health percentage is greater than 50. If so, it branches to HealthSkip, preventing the script from executing line 13.<br />
<br />
Line 14 sets the color of the health text to red<br />
<br />
Line 15 is the label that will be branched to from Line 13 to skip the red coloring<br />
<br />
Line 16 again uses character attribute substitution and the passed parameter value to output a display line containing the character name, the colorized health total, and the percentage value. The percentage is right-justified.<br />
<br />
Line 17 returns from the HealthCheck subroutine.<br />
<br />
=== Expanded Magic Missile Script ===<br />
<br />
This is the expanded and enhanced version of the Magic Missile script covered in {{yt|watch?v=u50xvNzS9Zk | this video}}. It includes visual and audio effects, checking and deducting spell slots, and applying damage using either Token-Mod or Alterbars.<br />
<br />
<pre><br />
!scriptcard {{ <br />
--#title|Magic Missile<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
<br />
-->GetAndCheckSlotInformation|<br />
<br />
--=MissileCount|[$SlotLevel] + 2<br />
--=DisplayCount|1<br />
--=MissileDamage|0<br />
--#leftsub|Slot level [$SlotLevel]<br />
--#rightsub|Ranged Attack<br />
--#emoteText|@{selected|character_name} uses a level [$SlotLevel.Total] spell slot to fire [$MissileCount.Total] missiles of magical force!<br />
<br />
--:MissileLoop|<br />
-->FireMissile|<br />
--=DisplayCount|[$DisplayCount] + 1<br />
--?[$DisplayCount] -le [$MissileCount]|MissileLoop<br />
--+Total|Total damage is [$MissileDamage]<br />
-->DeductSpellSlot|<br />
--#rightsub|Level [$SlotLevel] Left: [$SlotsRemaining] <br />
-->PlayEffects|none;burst-smoke;beam-magic;spell_01<br />
-->ApplyDamageTokenmod|@{target|token_id};3;-[$MissileDamage]<br />
-->ApplyDamageAlterbars|@{target|token_id};3;-[$MissileDamage]<br />
--X|<br />
<br />
--:FireMissile|<br />
--=ThisMissile|1d4 + 1<br />
--=MissileDamage|[$MissileDamage] + [$ThisMissile]<br />
--+Missile|[$DisplayCount.Total] Hits for [$ThisMissile] [b]force[/b] damage<br />
--<|<br />
<br />
--:GetAndCheckSlotInformation|<br />
--=SlotLevel|?{Spell Slot Level?|1|2|3|4|5|6|7|8|9}<br />
--=SlotsTotal|[*S:lvl[$SlotLevel]_slots_total]<br />
--=SlotsExpended|[*S:lvl[$SlotLevel]_slots_expended]<br />
--?[$SlotsExpended.Total] -ge [$SlotsTotal.Total]|NoSlotsLeft<br />
--<|<br />
<br />
--:NoSlotsLeft|<br />
--+|[*S:character_name] has no level [$SlotLevel.Total] spell slots available.<br />
--X|<br />
<br />
--:DeductSpellSlot|<br />
--=SlotsExpended|[$SlotsExpended] + 1<br />
--@setattr|_charid [*S:character_id] _lvl[$SlotLevel]_slots_expended|[$SlotsExpended] _silent<br />
--=SlotsRemaining|[$SlotsTotal] - [$SlotsExpended]<br />
--<|<br />
<br />
--:PlayEffects|Parameters are : source effect; target effect; line effect; sound effect<br />
--vtoken|@{selected|token_id} [%1%]<br />
--vtoken|@{target|token_id} [%2%]<br />
--vbetweentokens|@{selected|token_id} @{target|token_id} [%3%]<br />
--@roll20AM|_audio,play,nomenu|[%4%]<br />
--<|<br />
<br />
--:ApplyDamageTokenmod|Parameters are tokenid;bar#;amount<br />
--@token-mod|_ignore-selected _ids [%1%] _set bar[%2%]_value|[%3%]<br />
--<|<br />
<br />
--:ApplyDamageAlterbars|<br />
--@alter|_target|[%1%] _bar|[%2%] _amount|[%3%]<br />
--<|<br />
}}<br />
</pre><br />
<br />
[[Category:Featured articles]]</div>5004103https://wiki.roll20.net/Script:ScriptCardsScript:ScriptCards2021-10-05T22:21:00Z<p>5004103: /* Roll Variable Assignment (--=) */</p>
<hr />
<div>{{revdate}}<br />
== Introduction ==<br />
'''ScriptCards''' provides a script interpreter that can be used to create powerful macros that display the results of player/NPC actions, or display other information in a pleasing visual format in your game's chat window. The scripting language contains variables (both dice-roll (enhanced numerics) and strings) as well, conditionals, branching, subroutines with parameters, and a set of built-in functions to simplify working with Roll20 information.<br />
{{script overview<br />
|name=ScriptCards<br />
|author={{user profile|2365448|Kurt J.}}<br />
|code=<br />
|version=1.4.0e<br />
|lastmodified=2021-09-24}}<br />
ScriptCards is not game-system specific, and can be used with any system/sheet. Near the end of this Wiki there is a section set aside for libraries that can implement system-specific tasks, with the hope that enthusiasts playing particular systems will create and share utility functions that can be utilized by the wider community.<br />
<br />
The default display style for ScriptCards output is similar to the format used to document player and NPC abilities in Dungeons and Dragons 4th Edition, but does not have any system ties to D&D4E.<br />
<br />
Current OneClick Version : 1.4.0e<br />
<br />
Current Development Version : 1.4.4<br />
<br />
'''''<big>Critically Important: ScriptCards does not use/parse inline rolls. ScriptCards includes its own built-in dice roll parser to allow for the use of variables inside dice rolls. As of version 1.2.3, ScriptCards will now take inline rolls and substitute the total result value in statement strings, meaning that you can utilize inline rolls but ScriptCards will only see the result of the roll, and not parse the roll components itself.</big>'''''<br />
<br />
* {{fpl|9752053/ ScriptCards thread}}<br />
** {{fpl|10000297/ Scritpcard API Working and Sharing}}<br />
* https://github.com/kjaegers/ScriptCards/tree/main/ScriptCards_API - GitHub repository for source before the one-click version is updated.<br />
* {{yt.be|hyR7Jnq4mQM ScriptCards Intro}} 45min, Jan 2021<br />
* {{yt.be|u50xvNzS9Zk ScriptCards Magic Missile Deep Dive}} 39min, Feb 2021<br />
<br />
<br />
__TOC__<br />
=== Is ScriptCards Related to [[PowerCards]]? ===<br />
<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
Check the '''[[#What to Know if you are Coming from PowerCards|What to Know if you are Coming from PowerCards]]'''-section for a comparison table between the two scripts.<br />
<br />
== What is a ScriptCard Script ==<br />
<br />
A ScriptCard Script is text written into the chat window (either typed directly, pasted, or run via a macro) that will produce a card of information in the [[text Chat|chat window]]. A ScriptCard Script is composed of an [[API]] command: <code><nowiki>!scriptcard {{ }}</nowiki></code> enclosing any number of lines that determine the output that will be added to the card. At it simplest, the following macro:<br />
<br />
<pre>!scriptcard {{ }}</pre><br />
<br />
Will produce just a title card that displays “ScriptCards” as the name:<br />
<br />
[[File:Scriptcard blank.png]]<br />
<br />
Of course, this is just the simplest type of macro and isn’t very useful. In order to produce useful output, we need to include lines between the <code><nowiki>{{</nowiki></code> and <code><nowiki>}}</nowiki></code> that direct the API script as to what it should do.<br />
<br />
== Structure of a ScriptCard Line ==<br />
<br />
All ScriptCard lines begin with two dashes, followed by an ''statement identifier character'' that lets ScriptCards what type of line it is. There are several of these, and they are detailed in the next section. After the line type identifier, a Tag name 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.<br />
<br />
Following the Tag is a vertical bar, and then the content of the line itself. Again, each type of line might interpret this content differently.<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Identifier !! Statement Type !! Tag !! Content !! Notes<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--/</nowiki> || Comment || unused || unused || The <code>--/</code> 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--#</nowiki> || 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").<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--+</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--=</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--&</nowiki> || Assign String 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. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--@</nowiki> || 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 (i.e., [[TokenMod|!token-mod]], or [[ChatSetAttr|!setattr]], etc.)<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--:</nowiki> || 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<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--^</nowiki> || Branch To || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--></nowiki> || Call Procedure || 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<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--<</nowiki> || 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.<br />
|- <br />
| style="white-space:nowrap" | <nowiki>--?</nowiki> || Conditional Branch || Condition to be evaluated || True Branch Label<nowiki>|</nowiki>False Branch Label || The condition will be evaluated and execution will jump to one of the two indicated branches (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 included a semicolon separated list of parameters. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--s</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--l</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--v</nowiki> || 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+'''''<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--e</nowiki> || Echo to Chat || Name to send chat command as || Chat message to send || Variable substitution takes place on the tag and content.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--R</nowiki> || Retrieve Repeating Section Row information || "find", "first", or "next" || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--~</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--c</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--i</nowiki> || Information Request || User Prompt;Button Caption || InfoType;VariableName;ParameterText || See full documentation below.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--d</nowiki> || 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. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--%</nowiki> || 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. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--*</nowiki> || 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.<br />
|}<br />
<br />
== ScriptCard Statement Type Details ==<br />
The sections below detail the individual statement types supported by ScriptCards<br />
<br />
=== Comment (--/) ===<br />
<br />
A --/ statement is ignored by the ScriptCards parser. You can use this type of statement to add comments and informational text to your script. <br />
<br />
Example:<br />
<pre><br />
!script {{<br />
--/|Script Name : Fireball<br />
--/|Purpose : Allow the player to cast a fireball and blow stuff up!<br />
.<br />
.<br />
.<br />
}}<br />
</pre><br />
<br />
=== Set Parameter (--#) ===<br />
<br />
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.<br />
<br />
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.<br />
<br />
'''''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.'''''<br />
<br />
Examples:<br />
<pre><br />
--#title|Magic Missile<br />
--#leftsub|Level 1 Spell<br />
--#rightsub|Force Damage<br />
</pre><br />
<br />
The three examples above set the “title”, “leftsub”, and “rightsub” values for the card to the content value for the line. <br />
<br />
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.<br />
Settings Lines do not produce output lines on the card.<br />
<br />
The following settings are available (note that parameter names are ''not'' case sensitive):<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Name !! Effect/Use !! Default Value !! Type<br />
|-<br />
| 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<br />
|-<br />
| allowplaintextinrolls || If set to a non-zero value, plain character text in rolls will be copied to the roll text || 0 || Per-Line<br />
|-<br />
| bodyFontFace || Name of the font used in the card rows || Helvetica || Global<br />
|-<br />
| bodyFontSize || Size of the text in the card rows || 14px || Global<br />
|-<br />
| bodybackgroundimage || Specify an image (content for a CSS background-image tag) for the body area || none || Global<br />
|-<br />
| buttonBackground || Background color for buttons created with [button][/button] || #1C6EA4 || Per-Line<br />
|-<br />
| buttonBorderColor || Border (outline) color for buttons created with [button][/button] || #999999 || Per-Line<br />
|-<br />
| buttonFontFace || Font Family specifier for captions on buttons created with [button][/button] || Tahoma || Per-Line<br />
|-<br />
| buttonFontSize|| Text size for captions on buttons created with [button][/button] || x-small || Per-Line<br />
|-<br />
| buttonTextColor|| Text color of labels on buttons created with [button][/button] || #FFFFFF || Per-Line<br />
|-<br />
| 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<br />
|-<br />
| deferralcharacter || Changes the meta script deferral sequence to the specified value || ^ || Per-Line<br />
|-<br />
| diceFontColor|| Color of the dice created with the [d4] [d6], etc. formatting markers || #1C6EA4 || Per-Line<br />
|-<br />
| dicefontsize || Size of the dice created with the [d4] [d6], etc. formatting markers || 3.0em || Per-Line<br />
|-<br />
| 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<br />
|-<br />
| disablerollprocessing || If set to a non-zero value, --= lines will not process dice rolls strings || 0 || Per-Line<br />
|-<br />
| emoteBackground || Background color of the emote area || #f5f5ba || Global<br />
|-<br />
| emoteFont || Name of the font used in emote area (above the title of the output card) || Georgia || Global<br />
|-<br />
| emoteFontColor || Color of the font in the emote area || None (Empty) || Global<br />
|-<br />
| emoteFontSize || Size of the font used in the emote area || 14px || Global<br />
|-<br />
| emoteFontWeight || Font weight for the font in the emote area || bold|| Global<br />
|-<br />
| emoteState || If set to anything other than "visible", the emote portion of the card will not be displayed || visible || Global<br />
|-<br />
| emoteText || Text to display in the emote portion of the card || None (Empty) || Global<br />
|-<br />
| emotefont || Name of the font used in the emote text area || font-family: Georgia, serif; font-weight: bold; || Global<br />
|-<br />
| evenRowBackground || Hex code for the background color for even rows || #eeeeee || Per-Line<br />
|-<br />
| evenRowFontColor || Hex code for the text color for even rows || #000000 || Per-Line<br />
|-<br />
| evenrowbackgroundimage || Specify an image (content for a CSS background-image tag) for the even card rows || none || Per-Line<br />
|-<br />
| executionlimit || Maximum number of script lines the interpreter will try to execute. This prevents "infinite loop" sandbox crashes || 40000 || Global<br />
|-<br />
| hideCard || If set to any non-default value, the entire card output will be suppressed || 0 || Global<br />
|-<br />
| 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<br />
|-<br />
| 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<br />
|-<br />
| lineheight || Vertical size of each line on the output card || normal || Per-Line<br />
|-<br />
| nominmaxhighlight || If set to anything other than "0", rolls will not display crit/fumble/mixed highlight colors. || 0 || Per-Line<br />
|-<br />
| norollhighlight || If set to anything other than "0", rolls will not be formatted (plain numbers) but will still get a tooltip with details ('''''v1.3.6b+''''') || 0 || Per-Line<br />
|-<br />
| oddRowBackground || Hex code for the background color for even rows || #d0e4f5 || Per-Line <br />
|-<br />
| oddRowFontColor || Hex code for the text color for odd rows || #000000 || Per-Line<br />
|-<br />
| oddrowbackgroundimage || Specify an image (content for a CSS background-image tag) for the odd crd rows || none || Per-Line<br />
|-<br />
| reentrant || Used to name a script for rentrant button use || 0 || Global<br />
|-<br />
| 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)0 || Global<br />
|-<br />
| rollhilightlineheight || Determines the height of the hilight box placed around roll results ('''''1.4.2+''''') || 1.0em || Per-Line<br />
|-<br />
| roundUp || If set to a non-default value, integer division will round up instead of down || 0 || Per-Line<br />
|-<br />
| showfromfornonwhispers || If set to a non-zero value, will include the sender on cards that aren't whispered || 0 || Global<br />
|-<br />
| 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<br />
|-<br />
| subtitleFontColor || Color of the text in the subtitle areas || #FFFFFF || Global<br />
|-<br />
| subtitleFontFace || Name of the font used on the subtitle sections || Tahoma || Global<br />
|-<br />
| subtitleFontSize || Size of the subtitle font || 13px || Global<br />
|-<br />
| subtitleSeperator || The character(s) that will be placed between leftsub and rightsub || <nowiki>&#x2666</nowiki>; || Global<br />
|-<br />
| tableBorderRadius || CSS specifier for how rounded the borders of the output card are. Use "0px;" for square borders || 6px; || Global<br />
|-<br />
| tableShadow || CSS specifier for the drop shadow under the output card || 5px 3px 3px 0px #aaa; || Global<br />
|-<br />
| tablebgcolor || Background color of the whole card. '''''Normally not visible''''' || #EEEEEE || Global<br />
|-<br />
| tableborder || Color of the border that surrounds the whole card || 2px solid #000000; || Global<br />
|-<br />
| 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<br />
|-<br />
| timezone || IANA Specifier for the local time zone, used in system/date functions || merica/New_York || Per-Line<br />
|-<br />
| title || Text displayed in the title area of the card || ScriptCards || Global<br />
|-<br />
| titleCardBackground || A hex color code representing the background color of the title area. || #1c6ea4 || Global<br />
|-<br />
| titleFontColor || Color of the text on the card title || #FFFFFF || Global<br />
|-<br />
| titleFontFace || Name of the font used on the title area || Contrail One || Global<br />
|-<br />
| titleFontLineHeight || Line spacing on the title area || 1.2em || Global<br />
|-<br />
| titleFontSize || Size of the title font || 1.2em || Global<br />
|-<br />
| titlecardbackgroundimage || Specify an image (content for a CSS background-image tag) for the title card area || none || Global<br />
|-<br />
| titlecardbottomborder || Border CSS specifier for the bottom of the title card area || 2px solid #444444; || Global<br />
|-<br />
| titlecardgradient || If set to non-zero value, will place a vertical gradient on the title card area || 0 || Global<br />
|-<br />
| usehollowdice || If set to a non-zero value, the hollow/outline versions of the dice fonts will be used || 0 || Per-Line<br />
|-<br />
| whisper|| Comma separated list of who to whisper the output to. Use "gm" for [[GM|GMs]] and "self" for the sender || none || Global|}<br />
|}<br />
<br />
''Setting Lines do not produce output lines on the card''<br />
<br />
=== Direct Output (--+) ===<br />
<br />
A direct output line display 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.<br />
<br />
Examples of Direct Output lines:<br />
<pre><br />
--+Hello|World<br />
--+Attack|The monster rolls [$Attack] to hit!<br />
--+Damage|@{target|token_name} is hit for [$Damage] [#3333AA][b]frost[/b][/#] damage.<br />
</pre><br />
<br />
Direct Output lines support inline formatting, roll variable replacement, character attribute references, and procedure variables.<br />
<br />
=== GM Output (--*) ===<br />
<br />
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. <br />
<br />
Example:<br />
<pre><br />
--+PlayerLine|This line is shown on the public card<br />
--*GMLine|This line will only be shown to GMs, on a separate card.<br />
</pre><br />
<br />
=== Roll Variable Assignment (--=) ===<br />
<br />
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.<br />
<br />
'''''All components of a roll equation should be separated with spaces.'''''<br />
<br />
Examples:<br />
<pre><br />
--=MissileDamage|1d4 + 1<br />
--=Attack|1d20 + @{selected|strength_mod} [STR] + @{selected|pb} [PROF]<br />
</pre><br />
<br />
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. Text enclosed in square brackets ([]) is considered "flavor text" and will be added to the result text but does not impact the roll result.<br />
<br />
The following dice formats are supported:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Format Pattern !! Example !! Description<br />
|-<br />
| XdY || 3d8 || Simple format. Roll a Y-sided die X times<br />
|-<br />
| XdYkhZ || 2d20kh1 || Roll Y-sided die X times and keep the highest Z number of dice<br />
|-<br />
| XdYklZ || 4d6kl3 || Roll Y-sided die X times and keep the lowest Z number of dice <br />
|-<br />
| XdY>Z || 5d6>3 || Roll Y-sided die X times and count a 1 for each roll greater than Z <br />
|-<br />
| XdY<Z || 5d6<3 || Roll Y-sided die X times and count a 1 for each roll less than Z <br />
|}<br />
<br />
'''''Note: The dice formulae below are supported in the development version of ScriptCards and will be merged with the table above when activated on OneClick'''''<br />
::{| class="wikitable"<br />
|-<br />
! Format Pattern !! Example !! Description<br />
|-<br />
| 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<br />
|-<br />
| 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<br />
|-<br />
| 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)<br />
|-<br />
| 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<br />
|}<br />
<br />
The following operators are supported in a roll equation:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Operator !! Operation<br />
|-<br />
| + || Addition <br />
|-<br />
| - || Subtraction <br />
|-<br />
| * || Multiplication <br />
|-<br />
| / || Division <br />
|-<br />
| \ || Integer Division (Rounds down) <br />
|-<br />
| % || Modulo (Remainder of Divison)<br />
|}<br />
<br />
Roll Variables can be accessed at any time after they have been created by using the [$VariableName] format, with the following optional modifiers:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Modifier !! Meaning<br />
|-<br />
| No modifier || In a Direct Output Line (<nowiki>--+</nowiki>) 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<br />
|-<br />
| .Total || The end result of the roll equation as an unformatted number <br />
|-<br />
| .Base || The cumulative result of any dice rolled in the Roll Text (Numeric modifiers are not included) <br />
|-<br />
| .Ones || The number of dice in the roll that came up as 1s <br />
|-<br />
| .Aces || The number of dice in the roll that came up as the maximum number on the die <br />
|-<br />
| .Odds || The number of dice in the roll that came up with an odd number <br />
|-<br />
| .Evens || The number of dice in the roll that came up with an even number <br />
|-<br />
| .RollText || The raw text of the roll that was use to generate the results <br />
|-<br />
| .Text || A text representation of the results of the roll, including the numbers rolled for each die <br />
|-<br />
| .tableEntryText || The text portion of the result of a table roll<br />
|-<br />
| .tableEntryImgURL || The image source portion of the result of a table roll<br />
|-<br />
| .tableEntryValue || Numeric value of tableEntryText (via parseInt). If a non-numeric value, will be 0<br />
|-<br />
| .Raw || The total numeric result without any formatting, even if placed somewhere formatting would normally be done. <br />
|}<br />
<br />
Examples:<br />
<pre><br />
--+Total Damage|[$MissileDamage.Total] (roll was 1d4+1)<br />
--+Base Damage|[$MissileDamage.Base] (without the +1)<br />
--=Attack|1d20 + @{selected|strength_mod} [STR] + @{selected|pb} [PROF] + [$BlessBonus] [Bless]<br />
</pre><br />
<br />
In this case, 1d4 will be rolled and stored in “BlessBonus”, which can then be used in the Attack line.<br />
<br />
'''''Mathematical Functions in Roll Expressions '''''<br />
<br />
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:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Expression !! Meaning<br />
|-<br />
| {ABS} || Absolute Value<br />
|-<br />
| {CEIL} || Ceiling value (round up to the next whole number)<br />
|-<br />
| {FLOOR} || Floor value (round down to the next whole number)<br />
|-<br />
| {ROUND} || Round value (round up if the decimal portion is greater than 0.5, otherwise round down)<br />
|-<br />
| {NEGATE} || Multiply the value by negative one.<br />
|-<br />
| {SQRT} || Take the square root of the running value. ('''''1.4.1+''''')<br />
|-<br />
| {SQUARE} || Square the running value. ('''''1.4.2+''''')<br />
|-<br />
| {CUBEROOT} || Take the cube root of the running value. ('''''1.4.2+''''')<br />
|-<br />
| {CUBE} || Cube the running value. ('''''1.4.2+''''')<br />
|-<br />
| {SIN} || Return the SIN of running value. ('''''1.4.2+''''')<br />
|-<br />
| {COS} || Return the COS of running value. ('''''1.4.2+''''')<br />
|-<br />
| {TAN} || Return the TAN of running value. ('''''1.4.2+''''')<br />
|-<br />
| {ASIN} || Return the ASIN of running value. ('''''1.4.2+''''')<br />
|-<br />
| {ACOS} || Return the ACOS of running value. ('''''1.4.2+''''')<br />
|-<br />
| {ATAN} || Return the ATAN of running value. ('''''1.4.2+''''')<br />
|}<br />
<br />
Here are the syntax rules when using the above listed functions:<br />
<br />
Example 1.<br />
<br />
<pre><br />
!script {{<br />
--=output|2.9 {FLOOR}<br />
--+output|[$output]<br />
}}<br />
</pre><br />
<br />
The output from this example is "2".<br />
<br />
Example 2.<br />
<br />
<pre><br />
!script {{<br />
--=output|2.9 {FLOOR} {NEGATE} - 3<br />
--+output|[$output]<br />
}}<br />
</pre><br />
<br />
The output from this example is "-5".<br />
<br />
Basically, the function will use as its input whatever the current "running total" is.<br />
<br />
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.<br />
<br />
<br />
'''''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 <nowiki>[[ ]]</nowiki> 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.<br />
<br />
'''''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.<br />
<br />
'''Rolling on Rollable Tables'''<br />
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.<br />
<br />
''Roll Variable Lines do not produce output lines on the card.''<br />
<br />
=== String Variable Assignment (--&) ===<br />
<br />
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:<br />
<br />
<pre><br />
--&MyText|Hello<br />
</pre><br />
<br />
Here, we assign the text "Hello" to the string variable named MyText. You can also append text to a string variable by prefixing the content with a + sign:<br />
<br />
<pre><br />
--&MyText|+ World<br />
</pre><br />
<br />
If run after the statement above, MyText will now contain "Hello World".<br />
<br />
String variables can be referenced using the syntax [&variablename]<br />
<br />
=== Call API (--@) ===<br />
<br />
ScriptCards can use a Call API instruction to execute other API commands. The Tag contains the API 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 API command is executed.<br />
<br />
Examples:<br />
<pre><br />
--@eh|list<br />
--@alter|_target|@{target|token_id} _bar|3 _amount|-[$Damage]<br />
</pre><br />
<br />
In the first example above, the command <code>!eh list</code> will be executed, calling [[EncounterHelper]]. In the second, {{fpl|1216260/ AlterBars}} is called to modify a token's Bar 3 value.<br />
<br />
'''''Note:''''' When ScriptCards (or any API script) runs other API 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).<br />
<br />
See [[API:Script Index]] for more options.<br />
<br />
=== Branch Label (--:) ===<br />
<br />
A branch label defines a line in your code that can be reached by one of the branching instructions (<nowiki>--^</nowiki>, <nowiki>--></nowiki>, or <nowiki>--?</nowiki>). The Tag serves as the label name, and must be unique on the card.<br />
<br />
The vertical bar (|) separator must be present, but the content portion of the line is unused and can be treated as a comment.<br />
<br />
Examples:<br />
<pre><br />
--:MyLoop|<br />
--:CriticalHit|Will jump here if we roll a critical hit!<br />
</pre><br />
<br />
''A Branch Label line does not produce an output line on the card.''<br />
<br />
=== Branch (--^) === <br />
<br />
A Branch line 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.<br />
<br />
Examples:<br />
<pre><br />
--^MyLoop|Jumps to MyLoop<br />
--^SkipCrit|We didn't crit, so skip the Crit code<br />
</pre><br />
<br />
''A Branch line does not produce an output line on the card.''<br />
<br />
=== Call Procedure (-->) ===<br />
<br />
Similar to a branch, a Call Procedure (sometimes knows 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 (<nowiki>--<</nowiki>) 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 (;).<br />
<br />
Examples:<br />
<pre><br />
-->FixFormat|#3333FF;#999999<br />
</pre><br />
<br />
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%].<br />
<br />
=== Return (--<) ===<br />
<br />
A return instruction marks the end of a Gosub procedure. 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.<br />
<br />
Examples:<br />
<pre><br />
--<|<br />
--<|End of MySub<br />
</pre><br />
<br />
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.<br />
<br />
=== Conditional Statement (--?) ===<br />
<br />
A conditional statement contains some equation in the Tag that will be evaluated. '''''If any part of the comparison can/does contain a space, it needs to be surrounded by double quotes'''''<br />
<br />
Based on the true/false result of the evaluation, one of two execution paths will be taken. These execution paths are detailed in the content section of the statement. The "if true" path is specified first (directly after the vertical bar), and the "if false" path is specified after it, also separated by a vertical bar.<br />
<br />
Example:<br />
<pre><br />
--?[$AttackRoll.Total] -ge [$TargetAC]|Hit|Miss<br />
</pre><br />
<br />
'''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.'''<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Branch Format !! Meaning<br />
|-<br />
| Label || If just a label is specified, execution will branch to that label when the comparison is matched.<br />
|-<br />
| >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 <br />
|-<br />
| =VariableName || The roll variable "VariableName" will be assigned the value following a semicolon (ex: --?1 -eq 1|=Roll;1d20)<br />
|-<br />
| &VariableName || The string variable "VariableName" will be assigned the value following a semicolon (ex: --?1 -eq 1|&Result;Hit|&Result;Miss)<br />
|-<br />
| % or %! || The current for...next loop will perform the "next" action (%) or will break out (%!) <br />
|-<br />
| [ || Code block (see below)<br />
|}<br />
<br />
Examples:<br />
<pre><br />
--?[$AttackRoll.Base] -eq 20|CriticalHit<br />
--?[$AttackRoll.Base] -eq 1|>Fumble;@{selected|dexterity_mod}<br />
--?"@{target|npc_type}" -inc "undead"|&MonsterType;Undead|&MonsterType;Not Undead<br />
--?[$Attack.Total] >= [$ArmorClass]|>Hit|>Miss<br />
</pre><br />
<br />
In the first example, if the Base value of AttackRoll is a 20 (natural 20 on the die) execution will branch to the CriticalHit label.<br />
<br />
In the second example, 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%].<br />
<br />
The third example looks for the word "undead" in the npc_type attribute of the targeted character. If it exists in the text, the MonsterType string variable will be set to "Undead", otherwise it will be set to "Not Undead". <br />
<br />
The final example would call 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.<br />
<br />
''Text that does/may contain a space should be enclosed in double quotes.''<br />
<br />
The following comparison operators are available:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Comparator !! Meaning<br />
|-<br />
| -eq || Equal To <br />
|-<br />
| -eqi || Case insensitive Equal To <br />
|-<br />
| -ne || Not Equal To <br />
|-<br />
| -nei || Case insensitive Not Equal To <br />
|-<br />
| -gt || Greater Than <br />
|-<br />
| -ge || Greater Than or Equal To <br />
|-<br />
| -lt || Less Than <br />
|-<br />
| -le || Less Than or Equal To <br />
|-<br />
| -inc || Includes (text strings). <br />
|-<br />
| -ninc || Does Not Include (text strings). <br />
|}<br />
<br />
Multi-part conditionals are supported with -and and -or as separators. For example:<br />
<br />
<pre><br />
--?[$Attack.Total] -ge @{target|npc_ac} -and [$Attack.Base] -ne 20|HitButNotCrit<br />
</pre><br />
<br />
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):<br />
<br />
true AND false OR true<br />
<br />
Will be evaluated as true. The first two (true and false) will be false, but then false OR true will be true.<br />
<br />
Conversely:<br />
<br />
true or false and false<br />
<br />
Will be false, because the first true and false will evaluate to true, and then true and false will be false.<br />
<br />
'''CODE BLOCKS'''<br />
<br />
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.<br />
<br />
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:<br />
<br />
<pre><br />
!script {{<br />
--=Roll|1d2<br />
--+Roll|[$Roll]<br />
--?[$Roll.Total] -eq 2|[<br />
--&Value|Yep!<br />
--+|We are inside the TRUE portion of the block<br />
--]|[<br />
--&Value|Nope<br />
--+|We are inside the FALSE portion of the block<br />
--]|<br />
--+After|the blocks!<br />
--+Value|[&Value]<br />
}}<br />
</pre><br />
<br />
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 --]|. <br />
<br />
At this time, blocks cannot be nested, and can only be created as part of a conditional (--[ is not a valid statement type)<br />
<br />
''A conditional statement does not produce a line of output on the card.''<br />
<br />
=== Case Statement (--c) ===<br />
<br />
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 (:). Each match condition includes a branch label that will be used if the test value matches the item. 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:<br />
<br />
<pre><br />
!script {{<br />
--#title|Case Statement Testing<br />
--=Roll|1d4<br />
--C[$Roll.Total]|1:>One;[$Roll]|2:>Two;[$Roll]|3:>Three;[$Roll]|4:>Four;[$Roll]<br />
--X|<br />
<br />
--:One| --+Value|was One ([%1%]) --<|<br />
--:Two| --+Value|was Two ([%1%]) --<|<br />
--:Three| --+Value|was Three ([%1%]) --<|<br />
--:Four| --+Value|was Four ([%1%]) --<|<br />
}}<br />
</pre><br />
<br />
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 variable as a parameter.<br />
<br />
=== Save and Load (--s and --l) ===<br />
<br />
This statement pair is used to either store (--s) or load (--l) data from persistent storage. Items stored in persistent storage remain between card rolls and between Roll20 sessions. There are two types of data that can be stored: settings and roll variables. <br />
<br />
Examples:<br />
<br />
<pre><br />
--Ssettings|GreenStyle<br />
--Srollvariables|FirstCardVars<br />
</pre><br />
<br />
In this case, the tag for the statement determines what type of item is being saved (settings or rollvariables). When saving settings, all non-default settings are written to the named setting storage value. When Roll Variables are saved, all variables that currently exist will be saved to the named storage value.<br />
<br />
Loading stored items simply requires the same command with the --l statement type:<br />
<br />
<pre><br />
--Lsettings|GreenStyle<br />
--Lrollvariables|FirstCardVars<br />
</pre><br />
<br />
When loading settings, all stored settings will be applied to the current card settings. You can override settings by changing them after the load.<br />
<br />
When loading roll variables, the saved variables will be added to (or overwrite if they have the same name) any variables on the current card. This means it is safe to create roll variables before the load statement.<br />
<br />
'''Practical Uses'''<br />
The major intended use of persistent storage is for storing card formats for use in later scripts. For example, the following script:<br />
<br />
<pre><br />
!scriptcard {{<br />
--#titlecardbackground|#22CC22<br />
--#oddrowbackground|#cceecc<br />
--#evenrowbackground|#99ee99<br />
--Ssettings|@{selected|token_name}<br />
}}<br />
</pre><br />
<br />
Would save the titlecardbackground, oddrowbackground, and evenrowbackground settings to a saved list named after the selected token's name. When creating cards for that token to run later, you could include the line:<br />
<br />
<pre><br />
--Lsettings|@{selected|token_name}<br />
</pre><br />
<br />
To load all of the settings at once. By creating these setting sets for each character, you can specify a different color scheme for each character that can then be used in cards with a single formatting line.<br />
<br />
There is a supplemental ! command added to support saved settings:<br />
<br />
<pre><br />
!sc-liststoredsettings<br />
</pre><br />
<br />
Will produce a list of all stored setting names, with buttons to list the setting values stored in each group and a button to delete groups as needed.<br />
<br />
=== Visual Effects (--v) ===<br />
<br />
The --v statement can be used to create visual effects on the tabletop. The tag portion of the statement can be either "token" or "betweentokens". The content portion of the statement contains the required parameters for the effect generation, separated by spaces. If the effect is "none", no effect will be played. If any other value that doesn't match a Roll20 effect name will result in a burst-fire effect.<br />
<br />
For "token" effects, the parameters are the token id for the token the effect happens on, followed by the effect specifier.<br />
<br />
Example:<br />
<pre><br />
--vtoken|@{selected|token_id} burst-fire<br />
</pre><br />
<br />
For "betweentoken" effects, the parameters are the source token id, the target token id, and the effect specifier.<br />
<br />
Example:<br />
<pre><br />
--vbetweentokens|@{selected|token_id} @{target|token_id} beam-magic<br />
</pre><br />
<br />
'''''Version 1.2.8+'''''<br />
<br />
An additional effect specifier, "point" is available in 1.2.8+. This specifier allows you to create a visual effect at a designated X/Y pixel coordinate. Future updates will add custom-vfx support to this option. The parameters are the X and Y coordinates and the effect descriptor. As of version 1.2.9, you can also use custom effect specifiers with Point effects:<br />
<br />
<pre><br />
--vpoint|150 200 burst-fire<br />
</pre><br />
<br />
=== Echo to Chat (--e) ===<br />
<br />
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.<br />
<br />
Example:<br />
<pre><br />
--eThe Ghost|/em hovers around @{selected|character_name}... BOO!<br />
</pre><br />
<br />
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).<br />
<br />
'''''Whispering'''''<br />
<br />
You can use the echo statement to send a whisper, but there's a trick to it. If you execute this code here:<br />
<br />
<pre><br />
--eThe Ghost|/w ExamplePlayerName Boo.<br />
</pre><br />
<br />
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.<br />
<br />
So, in conclusion, it's best to use something like this when you're sending a whisper:<br />
<br />
<pre><br />
!script {{<br />
--#hidecard|1<br />
--&sender|The Ghost<br />
--&receiver|ExamplePlayerName<br />
--&message|Boo.<br />
--e[&sender]|/w [&receiver] [&message]<br />
--eScriptCards|/w gm **Whispered from [&sender] to [&receiver]:** [&message] <br />
}}<br />
</pre><br />
<br />
This will ensure that the message appears in your chat feed as well.<br />
<br />
=== Repeating Section Access (--R) ===<br />
<br />
ScriptCards (as of v0.0.13) supports accessing repeating section rows on a character sheet (for example: the attacks, the items, and the repeating resources) with the --R statement type. <br />
<br />
There are three basic commands you can use with --R, and they are specified by <br />
the tag used:<br />
<br />
<br />
'''''The "find" tag'''''<br />
<br />
An Rfind statement is used to search through a repeating field. Here is the general form of such a statement.<br />
<br />
<pre><br />
--Rfind|characterid;EntryName;SectionPrefix;SearchField<br />
</pre><br />
<br />
This is the most direct way to access a repeating section row. Supplying the character ID, followed by what you are looking for (Greatsword, for example), followed by the character sheet's section prefix (repeating_attack), followed by the field to check what you are searching for (atkname) will load the matching section (if found) into the script parsers memory. For example:<br />
<br />
<pre><br />
--Rfind|@{selected|character_id};Greatsword;repeating_attack;atkname<br />
</pre><br />
<br />
Will look at the character's "repeating_attack" section for an entry with an atkname value equal to "Greatsword". Similarly:<br />
<br />
<pre><br />
--Rfind|@{selected|character_id};Bite;repeating_npcaction;name<br />
</pre><br />
<br />
Will look for a "Bite" action on an NPC's action list.<br />
<br />
<br />
'''''The "first" tag'''''<br />
<br />
<pre><br />
--Rfirst|characterid;section prefix<br />
</pre><br />
<br />
This form of the --R command will look at all of the entries in the specified repeating section and load the first one into memory:<br />
<br />
<pre><br />
--Rfirst|@{selected|character_id};repeating_attack<br />
</pre><br />
<br />
Would load the character's first "repeating_attack" row into memory.<br />
<br />
<br />
'''''The "next" tag'''''<br />
<br />
<pre><br />
--Rnext|<br />
</pre><br />
<br />
No parameters are required for --Rnext, which loads the next entry in the list that was obtained with "first" into memory.<br />
<br />
<br />
'''''Section prefixes and how to use them'''''<br />
<br />
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 open [[D&D 5E by Roll20|this page]], and search for the phrase "repeating sections".<br />
<br />
<br />
'''''Additional information'''''<br />
<br />
However a row is obtained, it will be parsed to replace any attribute references (ie, @{level}) with the corresponding character attribute.<br />
<br />
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".<br />
<br />
You can reference repeating attribute data using the syntax [*R:attributename] syntax (similar to referencing standard character attributes).<br />
<br />
Here are some examples:<br />
<br />
Display the details of the "Greatsword" PC attack:<br />
<br />
<pre><br />
!script {{<br />
--Rfind|@{selected|character_id};Greatsword;repeating_attack;atkname<br />
--+Attack Name|[*R:atkname]<br />
--+Base Damage|[*R:dmgbase]<br />
}}<br />
</pre><br />
<br />
[[File:Scriptcards repeating greatsword.png|Repeating Greatsword Attack]]<br />
<br />
List all of the actions an NPC can take (just actions, not legendary, etc.)<br />
<br />
<pre><br />
!script {{<br />
--#title|NPC Actions<br />
--#leftsub|@{selected|token_name}<br />
--Rfirst|@{selected|character_id};repeating_npcaction<br />
--:DisplayLoop|<br />
--?"[*R:name]" -eq NoRepeatingAttributeLoaded|Done<br />
--+Action:|[*R:name] [*R:attack_damage] [*R:attack_damagetype]<br />
--?"[*R:attack_damage2]" -eq ""|NoSecondaryDamage<br />
--+ |[*R:attack_damage2] [*R:attack_damagetype2]<br />
--:NoSecondaryDamage|<br />
--Rnext|<br />
-->DisplayLoop| <br />
--:Done|<br />
}}<br />
</pre><br />
<br />
[[File:Scriptcards repeating npcactions.png]]<br />
<br />
In the script above, we get the "first" repeating_npcaction and display information about it. We then execute "next" and repeat until we run into "NoRepeatingAttributeLoaded".<br />
<br />
See the section named [[#Repeating Section Values|Repeating Section Values]] for more information.<br />
<br />
<br />
'''''Special debugging command: dump'''''<br />
<pre><br />
--Rdump|<br />
</pre><br />
<br />
The "dump" command will list all of the attributes ScriptCards knows about for the currently loaded repeating row to the API Console Log.<br />
<br />
=== Assign Variable to Built-In Function (--~) ===<br />
<br />
ScriptCards has the ability to run a function built into the API script and return the results to a variable. Some functions return roll variables, while others return strings. See the function table below for details. The format is:<br />
<br />
--~VariableName|function;param1;param2;param3;...<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Function Name !! Parameters !! Description<br />
|-<br />
| distance || token_A_ID;token_B_ID || Calculate the Chebyshev distance in grid units between two tokens. This is the measurement scheme D&D 4E/5E use for diagonal distance measurement<br />
|-<br />
| euclideandistance || token_A_ID;token_B_ID || Calculate the Euclidean distance between two tokens. This is essentially the Pythagorean theorem in action. Returns the result in grid units.<br />
|-<br />
| euclideanpixel || token_A_ID;token_B_ID || Calculate the Euclidean distance between two tokens and returns the result is pixels instead of grid units. <br />
|-<br />
| euclideanlong || token_A_ID;token_B_ID || 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 is calculated instead of before. More accurate over long distances. <br />
|-<br />
| manhattandistance || token_A_ID;token_B_ID || Also called "taxicabdistance" (which is an acceptable function name), this measures to how-many-over, how-many-up/down distance, disallowing diagonal movement.<br />
|-<br />
| getselected || none || 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 the first selected token, VariableName2 the second, etc.<br />
|}<br />
<br />
'''''Functions with Sub Functions'''''<br />
<br />
Most ScriptCards functions are grouped into set as sub functions. The table below lists the major functions and their sub functions.<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Function Name !! Sub Function !! Parameters !! Return Type !! Description<br />
|-<br />
| array || define || arrayname;value1;value2;... || none || Creates an array called "arrayname" and adds value1, value2, etc. to the array<br />
|-<br />
| array || sort || arrayname || none || Sorts the specified array in place in ascending order<br />
|-<br />
| array || add || arrayname;value1;value2;... || none || Adds value1, value2, ... to the existing array "arrayname"<br />
|-<br />
| array || remove || arrayname;value1;value2;... || none || Removes value1, value2, ... from the existing array "arrayname". Resets the array index to 0.<br />
|-<br />
| array || replace || arrayname;currentvalue;newvalue || none || Replaces all occurrences of "currentvalue" in "arayname" with "newvalue"<br />
|-<br />
| array || setatindex || arrayname;index;newvalue || none || Replaces the array item at index "index" with "newvalue"<br />
|-<br />
| array || getindex || arrayname || stringVariable || Retrieves the current index in "arrayname" and stores it in the supplied string variable<br />
|-<br />
| array || setindex || arrayname;newindex || none || Sets the current index in array "arrayname" to "newindex"<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| array || removeat || arrayname;indexposition || none || Removes the item at index "indexposition" from "arrayname". Resets the current array index to 0.<br />
|-<br />
| array || indexof || arrayname;searchvalue || stringVariable || Searches the array "arrayname" for and item with the value of "searchvalue" and, if found, returns the index of the first matching value or "ArrayError" if not found<br />
|-<br />
| array || getlength || arrayname || stringVariable || Returns the number of items in array "arrayname"<br />
|-<br />
| array || pagetokens || arrayname;tokenid;(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. 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.)<br />
|-<br />
| 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.<br />
|-<br />
| array || stringify || arrayname || stringVariable || Returns all of the items in "arrayname" as a string separated by semicolons (;)<br />
|-<br />
| array || fromstring || arrayname || delimiter;string || Creates an array from "string", splitting "string" on "delimiter" to separate the items<br />
|-<br />
| array || statusmarkers|| arrayname;tokenid || none|| Creates an array (arrayname) of the active statusmarkers (sometimes called Token Markers) for the specified tokenid<br />
|-<br />
| math || angle || math;angle;tokenid;tokenid|| rollVariable || Calculates the angle between two tokens and returns the value in degrees<br />
|-<br />
| math || ceil || math;ceil;value || rollVariable || Rounds '''value''' up to the next integer, dropping any decimal portion of the number<br />
|-<br />
| math || clamp || math;clamp;value;lowerBound;upperBound || rollVariable || Returns '''value''', but restricted to the range of '''loweBound''' and '''upperBound'''.<br />
|-<br />
| math || floor || math;floor;value || rollVariable || Rounds '''value''' down, dropping any decimal portion of the number<br />
|-<br />
| math || max || math;max;valueA;valueB || rollVariable || Returns the larger of '''valueA''' vs '''valueB'''<br />
|-<br />
| math || min || math;min;valueA;valueB || rollVariable || Returns the smaller of '''valueA''' vs '''valueB'''<br />
|-<br />
| math || round || math;round;value || rollVariable || Rounds '''value''' to the nearest integer<br />
|-<br />
| string || length || string;length;stringValue || rollVariable || Returns the length of '''stringValue''' in characters<br />
|-<br />
| string || before || string;before;searchText;stringValue || stringVariable || Searches '''stringValue''' for '''searchText''' and returns the portion of '''stringValue''' prior to that text<br />
|-<br />
| string || after || string;after;searchText;stringValue || stringVariable || Searches '''stringValue''' for '''searchText''' and returns the portion of '''stringValue''' after that text<br />
|-<br />
| string || left || string;left;count;stringValue || stringVariable || Returns the leftmost '''count''' characters of '''stringValue'''<br />
|-<br />
| string || right || string;right;count;stringValue || stringVariable || Returns the rightmost '''count''' characters of '''stringValue'''<br />
|-<br />
| string || replace || string;replace;searchText;replaceText;stringValue || stringVariable || Replaces '''searchText''' in '''stringValue''' with '''replaceText''' and returns the resulting string<br />
|-<br />
| string || replaceall || string;replace;searchText;replaceText;stringValue || stringVariable || Replaces all intances of '''searchText''' in '''stringValue''' with '''replaceText''' and returns the resulting string '''''Requires 1.2.9+'''''<br />
|-<br />
| string || trim || string;trim;stringValue || stringVariable || Removes leading and trailing spaces from stringValue and returns the result. <br />
|-<br />
| string || substring || string;substring;start;count;stringValue || stringVariable || Returns '''count''' characters starting at '''start''' from '''stringValue'''<br />
|-<br />
| 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.<br />
|-<br />
| string || tolowercase || string;tolowercase;stringValue || stringVariable || Converts the passed string to lower case and assigns to the passed variable name. <br />
|-<br />
| string || touppercase || string || stringVariable || Converts the passed string to upper case and assigns to the passed variable name. <br />
|-<br />
| 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. <br />
|-<br />
| 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.<br />
|-<br />
| 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'''.<br />
|-<br />
| turnorder || clear || none || none || Clears all entries from the {{Turn Tracker}}/Initiative<br />
|-<br />
| turnorder || addtoken || tokenid;trackervalue || none || Adds the token represented by "tokenid" to the initiative tracker with an initiavie value of "trackervalue"<br />
|-<br />
| turnorder || replacetoken || tokenid;trackervalue || none || Replaces the token represented by "tokenid" in the initiative tracker with an initiavie value of "trackervalue". Will add the token if it doesn't exist in the tracker.<br />
|-<br />
| turnorder || removetoken || tokenid || none || Removes the token represented by "tokenid" from the initiative tracker if it exists<br />
|-<br />
| turnorder || addcustom || textlabel;trackervalue || none || Add a custom text entry to the {{Turn Tracker}}/Initiative named "textlabel" with an initiative value of "trackervalue"<br />
|-<br />
| system || date || getdatetime || stringVariable || Returns the date time in the active timezone (see settings) <br />
|-<br />
| system || date || getdate || stringVariable || Returns the date in the active timezone (see settings) <br />
|-<br />
| system || date || gettime || stringVariable || Returns the time in the active timezone (see settings)<br />
|-<br />
| system || dumpvariables || "rolls", "string", or "array" || none || Dumps all of the defined variables of the indicated type to the console log<br />
|-<br />
| system || findability || system;findability;charactername;abilityname || stringVariable || Returns the object ID of the ability on the indicated character or "AbilityNotFound"<br />
|-<br />
|}<br />
<br />
Examples:<br />
<br />
<pre><br />
--~HowFarAway|distance;@{selected|token_id};@{target|token_id}<br />
</pre><br />
<br />
Returns the distance (Chebyshev) between the selected and target tokens and stores it in "HowFarAway".<br />
<br />
<pre><br />
--SelectedDudes|getselected<br />
</pre><br />
<br />
If 5 tokens were selected, 6 variables would be created: SelectedDudesCount (with a value of 5), SelectedDudes1, SelectedDudes2, SelectedDudes3, SelectedDudes4, SelectedDudes5.<br />
<br />
=== Information Request (--i) ===<br />
<br />
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.<br />
<br />
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.<br />
<br />
After the user has clicked the button and responded to the requests, ScriptCards will resume processing the script from where it left off.<br />
<br />
Here is an example “i” line:<br />
<br />
<pre><br />
--IScriptCards needs additional information to continue;Click to select a target and provide information|t;MyNewTarget;Missile1Target||q;MyNameIs;What is your name?<br />
</pre><br />
<br />
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.<br />
<br />
Supported information request types are “t” for target token, and “q” for query.<br />
<br />
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).<br />
<br />
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:<br />
<br />
<pre><br />
q;UserName;What is your name?|Fred|Bob|Sally|Nancy<br />
</pre><br />
<br />
Would have a dropdown menu with four choices.<br />
<br />
== Inline Formatting ==<br />
<br />
Inline formatting is processed on Direct Output lines only (--+ lines) and the following inline format markup is available:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Formatting Tags !! Description<br />
|-<br />
| [b]..[/b] || Bold the text between the markers <br />
|-<br />
| [i]..[/i] || Italicize the text between the markers <br />
|-<br />
| [u]..[/u] || Underline the text between the markers <br />
|-<br />
| [s]..[/s] || Strike-Thru the text between the markers <br />
|-<br />
| [c]..[/c] || Center alignment <br />
|-<br />
| [l]..[/l] || Left alignment <br />
|-<br />
| [r]..[/r] || Right alignment <br />
|-<br />
| [j]..[/j] || Full justification alignment <br />
|-<br />
| [#xxx]..[/#] or [#xxxxxx]..[/#] || Use a 3 or 6 digit hex code to colorize the text between the markers <br />
|-<br />
| [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, <code>[img width=128 height=128]</code> )<br />
|-<br />
| [button]caption::action[/button] || Create a button with the label "caption" that performs the action defined by "action". <br />
|-<br />
| [t] || Converted to HTML table tag. Text after the "t" will be included inside the tag (width, border, etc)<br />
|-<br />
| [/t] || Converted to HTML close table tag.<br />
|-<br />
| [tr] || Converted to HTML table row tag. Text after the "tr" will be included inside the tag<br />
|-<br />
| [/tr] || Converted to HTML close table row tag.<br />
|-<br />
| [td] || Converted to HTML table cell tag. Text after the "tr" will be included inside the tag<br />
|-<br />
| [/td] || Converted to HTML close table cell tag.<br />
|}<br />
<br />
== Variables ==<br />
<br />
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. While it is possible to assign both a string and a roll variable the same name, doing so will likely result in confusion when looking at the script later, so it is not recommended.<br />
<br />
String Variables are assigned with the --& statement and are referenced using [&variableName] notation.<br />
<br />
Roll Variables are assigned with the --= statement, and the assignment value is always processed by the ScriptCards Roll Processor (resolves dice rolls, etc.)<br />
<br />
There are a handful of variables assigned automatically when a ScriptCard is executed. These are all string variables, and are:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Variable !! Value<br />
|-<br />
| SendingPlayerID || Contains the object ID of the player that sent the macro<br />
|-<br />
| SendingPlayerName || Contains the display name of the player<br />
|-<br />
| SendingPlayerColor || Contains the color code associated with the player<br />
|-<br />
| SendingPlayerSpeakingAs || The contents of the "Speaking As" dropdown window<br />
|-<br />
| SendingPlayerIsGM || Contains 1 if the player is a GM, and 0 if the player is NOT a GM<br />
|}<br />
<br />
== Arrays ==<br />
<br />
Arrays are a special type of variable, and are managed by the function (<nowiki>--~</nowiki> command). All of the array function commands follow the same pattern:<br />
<br />
<pre>--~variableName|array;subcommand;arrayname;param1;param2;param3;...</pre><br />
<br />
Not all array commands return anything to "variableName". The function table above will specify the return type of the command if any.<br />
<br />
There are a couple of different ways to create an array:<br />
<br />
The '''define''' array subcommand creates (or recreates) an array and assigns it values - one for each included parameter after the array name. For example:<br />
<br />
<pre>--~|array;define;Fruits;mango;peach;strawberry;apricot;banana;apple</pre><br />
<br />
will create an array called '''Fruits''' with 6 elements in the order listed in the command (mango, peach, etc.)<br />
<br />
You can also use two other subcommands to create arrays based on tokens:<br />
<br />
<pre>--~Count|array;pagetokens;Everybondy;@{selected|token_id}</pre><br />
<br />
and<br />
<br />
<pre>--~Count|array;selectedtokens;Selected</pre><br />
<br />
In both cases, arrays of tokens will be created, and a string variable called "Count" will be set to the number of tokens in the array. The '''pagetokens''' command returns (by default) all of the tokens on the page that contains the token passed as the parameter after the array name. You can filter the tokens that "pagetokens" includes in the array by appending an optional parameter describing the type of token you are looking for:<br />
<br />
<pre>--~Count|array;pagetokens;Everybondy;@{selected|token_id};npc</pre><br />
<br />
Will return only tokens on the page that represent characters that do not have a ''controlledby'' parameter set. The available options are "all" (default), "char", "graphic", "pc", and "npc".<br />
<br />
The '''selectedtokens''' command returns an array with all of the tokens that were selected when the script was called.<br />
<br />
You can also use an arbitrary string to create an array, specifying a delimiter with the '''fromstring''' command:<br />
<br />
<pre><br />
--&names|Fred<br />
--&names|+,Sally<br />
--&names|+,Ted<br />
--&names|+,Joyce<br />
--~|array;fromstring;,;[&names]<br />
</pre><br />
<br />
The above example builds a comma-separated string and then uses "fromstring" to create an array with 4 elements from it, specifying the comma as the delimiter.<br />
<br />
Finally, you can use the '''statusmarkers''' command to create an array with one entry for each active status marker on a specified token:<br />
<br />
<pre>--~|array;statusmarkers;Conditions;@{selected|token_id}</pre><br />
<br />
will create an array with one entry for each status active on the selected token. The array elements will be the internal name of the status (if you are using custom status marker packs, the names will be specified in the marker pack).<br />
<br />
'''Traversing Arrays'''<br />
<br />
Each array keeps track of an internal index position (starting at 0). Several commands let you manage this index:<br />
<br />
*'''getindex''' returns the current index value<br />
*'''setindex''' sets the index to the specified location in the array<br />
*'''getlength''' returns the number of elements in the array<br />
*'''indexof''' returns the index location of the specified element<br />
<br />
Other commands let you retrieve values from the array:<br />
<br />
*'''getfirst''' sets the index to 0 and returns the value at that position<br />
*'''getnext''' advances the index by 1 and returns the new current value<br />
*'''getprevious''' reduces the index by 1 and returns the new current value<br />
*'''getlast''' sets the index to the last elements in the array and returns the new current value<br />
<br />
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.<br />
<br />
'''Manipulating Array Elements'''<br />
<br />
Several array commands deal with inserting, removing, and modifying elements:<br />
<br />
*'''add''' works just like define, except that it takes an existing array and adds elements to it based on the passed parameters<br />
*'''remove''' looks for items matching each passed parameter and removes them from the indicated array if they exist<br />
*'''removeat''' allows you to specify an index location in the array and remove the element at that position<br />
*'''replace''' searches an array for a value and replaces all occurrences of it with a new value (if found)<br />
*'''sort''' sorts the elements in the array in ascending order<br />
*'''strinfigy''' returns a string variable that includes each array element separated by semicolons (;) <br />
<br />
'''Referencing Array Elements'''<br />
<br />
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.<br />
<br />
<pre><br />
!script {{<br />
--~dummy|array;pagetokens;myarray;@{selected|token_id}<br />
--~count|array;getcount;myarray<br />
--+Total:|There are [&count] graphical objects on the page<br />
--~testvar|array;getfirst;myarray<br />
--:loop|<br />
--+Value|[*[&testvar]:character_name]<br />
--~testvar|array;getnext;myarray<br />
--?[&testvar] -ne ArrayError|loop<br />
--+Loop1|Is Done!<br />
}}<br />
</pre><br />
<br />
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:<br />
<br />
<pre><br />
!script {{<br />
--~dummy|array;pagetokens;myarray;@{selected|token_id}<br />
--~count|array;getcount;myarray<br />
--+Total:|There are [&count] graphical objects on the page<br />
--%loopCounter|1;[&count]<br />
--+Value|[*[@myarray([&loopCounter])]:character_name]<br />
--%|<br />
--+Loop|Is Done!<br />
}}<br />
</pre><br />
<br />
This line : <nowiki>--+Value|[*[@myarray([&loopCounter])]:character_name]</nowiki> uses [@arrayName(index)] format (inside a [*characterid:attribute] syntax) to perform the same task as running through the loop with the index.<br />
<br />
(Note: Additional examples are on the way...)<br />
<br />
== For...Next Loops ==<br />
<br />
For...Next loops in ScriptCards are supported with the with the --% statement type. A loop is defined by starting off with:<br />
<br />
<pre><br />
--%LoopCounter|<start>;<end>;[step]<br />
</pre><br />
<br />
The start and end values are required, while the step parameter is optional. If the step is omitted, it will be assumed to be 1. A string variable named after the line tag ("LoopCounter" in the case above) will be created and will hold the current iteration value for the loop. Here is a real example:<br />
<br />
<pre><br />
--%LoopCounter|1;10;1<br />
</pre><br />
<br />
This will begin a loop identified by "LoopCounter" that will start at 1, increasing by 1 each iteration (the step) until it has completed 10 executions.<br />
<br />
The "next" statement is simply <code>--%|</code>, with no tag or parameters. This indicates to ScriptCards that it should increment the counter and go back to the beginning of the loop. Extending the example above:<br />
<br />
<pre><br />
!script {{<br />
--%LoopCounter|1;10;1<br />
--=Roll|1d20<br />
--+Loop|Counter is [&LoopCounter], roll was [$Roll]<br />
--%|<br />
}}<br />
</pre><br />
<br />
The <code>--%!|</code> sequence will break out of the loop, no matter how many iterations are remaining.<br />
<br />
The % and %! character sequences can also be used as part of a 1.2.1+ non-branching conditional to continue or break the loop:<br />
<br />
<pre><br />
--?"X[&RollInto]X" -eq "XX"|%<br />
</pre><br />
<br />
In this example, if the string variable RollInfo is empty, the loop will return to the top and continue with the next iteration, while:<br />
<br />
<pre><br />
--?"X[&RollInto]X" -eq "XX"|%!<br />
</pre><br />
<br />
Would cause the whole loop to end if the condition were true.<br />
<br />
== Referencing ==<br />
<br />
=== Roll Variables===<br />
<br />
Roll Variables can be referenced from the content portion of any line type, and from the tag portion of conditional statements. The referenced value is replaced when the line is executed.<br />
<br />
There are several modifiers that can be used to reference parts of a roll:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Modifier !! Meaning<br />
|-<br />
| No modifier || In a Direct Output Line (<nowiki>--+</nowiki>), GM Output Line (<nowiki>--*</nowiki>), or String Assignement (<nowiki>--&</nowiki>), 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<br />
|-<br />
| .Total || The end result of the roll equation. Formatting rules for "No Modifier" apply based on line type. <br />
|-<br />
| .Raw || The total value of the roll variable without any formatting, no matter what kind of line the reference is used in.<br />
|-<br />
| .Base || The cumulative result of any dice rolled in the Roll Text (Numeric modifiers are not included) <br />
|-<br />
| .Ones || The number of dice in the roll that came up as 1s <br />
|-<br />
| .Aces || The number of dice in the roll that came up as the maximum number on the die <br />
|-<br />
| .Odds || The number of dice in the roll that came up with an odd number <br />
|-<br />
| .Evens || The number of dice in the roll that came up with an even number <br />
|-<br />
| .RollText || The raw text of the roll that was use to generate the results <br />
|-<br />
| .Text || A text representation of the results of the roll, including the numbers rolled for each die <br />
|-<br />
| .tableEntryText || The text portion of the result of a table roll<br />
|-<br />
| .tableEntryImgURL || The image source portion of the result of a table roll<br />
|-<br />
| .tableEntryValue || If the tableEntryText is purely numeric, will contain the numeric value<br />
|}<br />
<br />
=== String Variables ===<br />
<br />
To reference a string variable, use the notation [&variablename]. String variables can be referenced in direct output, roll variable assignment, and string variable assignment statements.<br />
<br />
=== Character/Token Attributes ===<br />
<br />
A character or token attribute can be referenced from content portion of any type of line and is substituted when the line is executed. The general format for referencing a character attribute is [*ID:attribute]. ID can be a token ID or a character ID (these start with a dash). Additionally if you have specified a sourceToken or targetToken, you can substitute "S" or "T" for the ID (for example [*S:npc_type] will retrieve the npc_type attribute from the source token.<br />
<br />
By default, all attribute references will be pulled from the '''''character''''' object that the ID represents (either directly or by being a Token ID that represents a character).<br />
<br />
Keep in mind, that if you want to access the "max" of a character attribute (for example, the max hit points), then you cannot trust the name that your roll20 character sheet shows you when you hover your mouse over the max hit points. For example, this reference will not work: [*S:hp_max]. Instead, you need to use this reference: [*S:hp^].<br />
<br />
If your ID refers to a token, token attributes can be accessed by preceding the attribute name with "t-", for example [*S:t-aura1_radius]. Supported token attributes are:<br />
<br />
{|<br />
| t-name || t-id || t-statusmarkers || t-bar1_value<br />
|-<br />
| t-bar1_max || t-bar2_value || t-bar2_max || t-bar3_value<br />
|-<br />
| t-bar3_max || t-top || t-left || t-width<br />
|-<br />
| t-height || t-rotation || t-layer || t-aura1_radius<br />
|-<br />
| t-aura1_color || t-aura2_radius || t-aura2_color || t-aura1_square<br />
|-<br />
| t-aura2_square || t-tint_color || t-light_radius || t-light_dimradius<br />
|-<br />
| t-light_angle || t-light_losangle || t-light_multiplier || t-light_otherplayers<br />
|-<br />
| t-light_hassight || t-flipv || t-fliph || t-controlledby<br />
|-<br />
| t-_cardid || t-_pageid || t-imgsrc || t-bar1_link<br />
|-<br />
| t-bar2_link || t-bar3_link || t-represents || t-layer<br />
|-<br />
| t-isdrawing || t-name || t-gmnotes || t-showname<br />
|-<br />
| t-showplayers_name || t-showplayers_bar1 || t-showplayers_bar2 || t-showplayers_bar3<br />
|-<br />
| t-showplayers_aura1 || t-showplayers_aura2 || t-playersedit_name || t-playersedit_bar1<br />
|-<br />
| t-playersedit_bar2 || t-playersedit_bar3 || t-playersedit_aura1 || t-playersedit_aura2<br />
|-<br />
| t-lastmove || t-adv_fow_view_distance || t-has_bright_light_vision || t-has_night_vision<br />
|-<br />
| t-night_vision_distance || t-emits_bright_light || t-bright_light_distance || t-emits_low_light<br />
|-<br />
| t-low_light_distance || t-has_limit_field_of_vision || t-limit_field_of_vision_center || t-limit_field_of_vision_total<br />
|-<br />
| t-has_limit_field_of_night_vision || t-limit_field_of_night_vision_center || t-limit_field_of_night_vision_total || t-has_directional_bright_light<br />
|-<br />
| t-directional_bright_light_center || t-directional_bright_light_total || t-has_directional_dim_light || t-directional_dim_light_center<br />
|-<br />
| t-directional_dim_light_total || t-lightColor || || |<br />
|}<br />
<br />
'''''It is important to note that some attributes names on tokens have corresponding attribute names on characters, which represent different values. For example, [*T:id] returns the character ID, while [*T:t-id] returns the token ID.'''''<br />
<br />
=== Subroutine Parameters ===<br />
<br />
When using a gosub statement (-->) or a conditional marked as a gosub (prefixing the label with a > character), you can pass any number of parameters separated by semicolons (;) that the code in the subroutine can utilize.<br />
<br />
Subroutine parameters are numbered starting at 1, and are accessed by using the notation [%number%], so the first parameter is [%1%], the second is [%2%], etc.<br />
<br />
Parameter substitution happens on all line types, and happens prior to character attribute references or roll variable substitution.<br />
<br />
=== Campaign Attribute ===<br />
You can retrieve properties of the API's Campaign object with the [*C:attributename] syntax. For example, [*C:playerpageid] will retrieve the current player ribbon page from the Campaign object.<br />
<br />
=== Page Attributes ===<br />
If you have set the '''activepage''' parameter, you can retrieve page-related properties with the [*P:attributename] syntax, including the page's UDL parameters.<br />
<br />
=== Repeating Section Values ===<br />
<br />
You can reference repeating attribute data using the syntax [*R:attributename] syntax (similar to referencing standard character attributes). The currently active repeating row information will be used to retrieve attribute values. You can also retrieve the full attribute name for a repeating row attribute by using the [*R>attributename] notation. This is useful to pass to things like chatsetattr.<br />
<br />
See the section named [[#Repeating Section Access (--R)|Repeating Section Access]] for more information.<br />
<br />
=== Array Elements ===<br />
After an array has been declared, the elements can be referenced with [@arrayName(index)]. Array indices start at 0.<br />
<br />
== Deferred Resolution for Meta Scripts ==<br />
<br />
As of 1.2.9, ScriptCards supports a deferral character for use when calling another API script with via the --@ statement, to defer processing of meta script references so they get processed prior to the sub-API call insted of prior to ScriptCards execution. To defer this processing for meta script (SelectManager, Fetch) by inserting a deferral character into the meta call. For example, if I want to have ScriptCards call TokenMod as if the token for "Quej Gr'stra" (yes, I let Roll20 name my test NPCs) I could use something like this:<br />
<br />
--@token-mod|{^& select Quej Gr'stra} _on showname<br />
<br />
The "^" in between { and & will prevent SelectManager from seeing the call when the ScriptCard script is processed, but the --@ statement will remove the deferral character so the command that will be sent by ScriptCards is:<br />
<br />
!token-mod {& select Quej Gr'stra} --on showname<br />
<br />
With the deferral character removed, SelectManager will see the {& select ...} and do its magic.<br />
<br />
While the default deferral character is "^", the deferral character is a setting that can be changed:<br />
<br />
--#deferralcharacter|%<br />
<br />
Will make % the deferral character for future --@ statements in the running script.<br />
<br />
There are currently three supported Meta script structures: {^&...} for SelectManager, @^(...) and *^(...) for fetch, where the ^ in the structures here represents the placement of the deferral character.<br />
<br />
== Arrays ==<br />
<br />
Arrays are a new data type introduced in version 1.1.12 of ScriptCards, and are manipulated with associated function (--~) commands.<br />
<br />
* Arrays are a lists of strings. Items in an array cannot contain the semi-colon (;) character, as that is used to separate parameters in the function code that deals with arrays.<br />
* Arrays are accessed via the --~ script command. In some cases, the value of the tag (variable name) for array commands is not used, and can be a dummy value or simply omitted. I have omitted them in the statements below.<br />
* All commands that DO return a value return string values, even if the content is numeric.<br />
* If a command returns a value and there is some sort of reason that it isn't an array value, you will get "ArrayError" in the return value. This can happen if you reach the end of an array while stepping through it, for example, so checking for "ArrayError" can serve as the end condition for a loop.<br />
* Each array keeps track of its current index, allowing you to step forward and backwards through arrays.<br />
* Any number of arrays can be defined.<br />
* Unlike string variables and roll variables, array variables cannot (currently) be referenced directly. It is necessary to use the function (--~) syntax to manipulate arrays and get values from them as strings for use in other parts of your script.<br />
<br />
<br />
== Reentrant Scripts ==<br />
<br />
Reentrant scripts allow you to create buttons in your script code that will re-execute the script at a given label within the code. If you set the reentrant setting (--#reentrant|somevalue) to a non-zero value, your setting and variable information will be preserved between executions. Reentrant script can be used to present menus or choices and then continue acting.<br />
<br />
Reentrant buttons are created with the [rbutton]Caption::ReentryLabel;Parameter[/rbutton] construct. The caption will be displayed on the generated button. ReentryLabel is the name of a label in your script that the button will jump to when clicked, and Parameter will be passed in as a string value called "reentryval".<br />
<br />
Example:<br />
<pre><br />
!script {{<br />
--#reentrant|testing<br />
--=Roll|1d20<br />
--+Roll|[$Roll]<br />
--&String|That was a [$Roll.Raw]!<br />
--~x|array;define;MyArray;Apple;Banana;Orange<br />
--+Try it|[rbutton]Hello!::EXEC_PC_SPELL;9[/rbutton]<br />
--X|<br />
<br />
--:EXEC_PC_SPELL|<br />
--+ReentryVal|[&reentryval]<br />
--+The value of Roll is|[$Roll]<br />
--+Value of String|[&String]<br />
--+Array|[@MyArray(0)]<br />
--X|<br />
}}<br />
</pre><br />
<br />
This script sets up some variables and then displays a button labeled "Hello!". If the user clicks the button, the script will be re-entered starting at the "EXEC_PC_SPELL", which will display the content of the variables from the original execution.<br />
<br />
'''''Note: This section needs to be expanded upon'''''<br />
<br />
== Procedure Libraries ==<br />
<br />
You can now create handouts in your game in Roll 20 with the name format "ScriptCards Library NAME", where name is a name you assign to the library. Library names are case sensitive. It is my hope that the more proficient ScriptCards scripters out there will provide procedure libraries (or procedures that can be included in libraries) for others to use to make their scripting life easier. Be they specific to a game system, or to a type of activity, I think a robust set of libraries that GMs could use to enhance their scripting capabilities would be very valuable to the community. Should such things begin to emerge, I’ll create a portion of the ScriptCards Wiki page to house them.<br />
<br />
To include one or more libraries in a script, use the +++libname+++ directive (does not need a -- line associated with it). Multiple library names can be specified by separating them with semicolons (i.e., +++General;dnd5elib;Colorize+++ would include three libraries (General, dnd5elib, and Colorize).<br />
<br />
Included libraries are separated from the main script code by the automatic inclusion of "--X|" before the first library is appended to the script, and all libraries are loaded at the end of the script before script processing takes place.<br />
<br />
Procedures and labels in libraries can be used just as if they were included in the body of your script. Note that this DOES mean that you could, technically, jump into a library with a direct branch (--^) or direct branch conditional, but I recommend using libraries to store reusable procedures.<br />
The Notes section of the library handout stores the library code, and is written just like any other ScriptCards code except:<br />
<br />
* They cannot use roll queries (?{Some Prompt:}) to get information from the user at execution time.<br />
* They cannot use @{} notation to access character and token information.<br />
<br />
Both of these limitation stem from the fact that Procedure Libraries are not processed by the chat server, which is what handles these items.<br />
<br />
Here is an example of handling damage modifications (resistance, vulnerability, and immunity) in D&D 5E with a library:<br />
<br />
<pre><br />
!script {{<br />
+++dnd5elib+++<br />
--#|Damage Modifiers Test<br />
--#targettoken|@{target|token_id}<br />
-->Lib5E_CheckDamageModifiers|ResistType;fire<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] fire damage<br />
<br />
-->Lib5E_CheckDamageModifiers|ResistType;cold<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] cold damage<br />
<br />
-->Lib5E_CheckDamageModifiers|ResistType;poison<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] poison damage<br />
<br />
-->Lib5E_CheckDamageModifiers|ResistType;acid<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] acid damage<br />
<br />
--X|<br />
}}<br />
</pre><br />
<br />
Library content (In a handout called “ScriptCards Library dnd5elib” NOTE: Paste into Notepad first and then paste into the handout in Roll20 to avoid bringing over HTML formatting from the web site):<br />
<br />
<pre><br />
--/|ScriptCards Library: dnd5elib version 0.0.1<br />
--/|Provides various utility procedures for D&D 5E games<br />
<br />
--/|Lib5E_CheckDamageModifiers handle damage resistance, vulnerability, and immunity. <br />
--/|Pass a string variable to be filled with a string to be appended to a dice roll and the damage type <br />
<br />
--:Lib5E_CheckDamageModifiers|damageVariableName;damageType<br />
--&[%1%]|<br />
--?"[*T:npc_vulnerabilities]" -inc "[%2%]"|>_Lib5E_IsVulnerable;[%1%]<br />
--?"[*T:npc_resistances]" -inc "[%2%]"|>_Lib5E_IsResistant;[%1%]<br />
--?"[*T:npc_immunities]" -inc "[%2%]"|>_Lib5E_IsImmune;[%1%]<br />
--<|<br />
<br />
--:_Lib5E_IsVulnerable| --&[%1%]| * 2 [Vulnerable] --<|<br />
--:_Lib5E_IsResistant| --&[%1%]| \ 2 [Resistant] --<|<br />
--:_Lib5E_IsImmune| --&[%1%]| * 0 [Immune] --<|<br />
</pre><br />
<br />
The idea is that the functions in the library create a string that can be appended to a roll to modify the output based on resistances, so you pass Lib5E_CheckDamageModifiers the name of the string variable you want to use and the damage type. The variable (ResistType in this case) will include either nothing, “* 2 [Vulnerable]”, “\ 2 [Resistant]”, or “* 0 [Immune]” which can be included in a roll assignment (--=) to modify the damage as appropriate. The order here might be important if an NPC is misconfigured to be both resistant and immune to the same damage type. Since immune is an absolute, having it last ensures that it will override resistant or vulnerable. A creature that is both vulnerable and resistant (again, misconfigured) will come back as resistant since that condition is checked after vulnerable.<br />
Some notes: I prefix my library labels with either “Lib5E_” or “_Lib5E_” as a clarity convention. This isn’t strictly necessary but you should be aware that if two libraries (or if your script and a library) define the same label, the last label defined will win. Since libraries are appended to the end of the script in the order you include them in the +++libname+++ directive, you can somewhat control this, but it is probably best to avoid re-declaring labels. <br />
<br />
In my case, items beginning with “Lib5E_” are intended to be called by scripts, while items beginning with “_Lib5E_” are intended to be used as subroutines by the “public” procedures. Of course, there is no reason you couldn’t call them directly.<br />
<br />
You might also note that I’ve included some library information in comment lines (--/|) at the top of the library. These are ignored by ScriptCards, and are a good way to convey requirements, parameters, usage information, etc.<br />
<br />
== Example Libraries ==<br />
<br />
=== dnd5elib ===<br />
<br />
[https://github.com/kjaegers/ScriptCards Download the dnd5elib Library from the ScriptCards GitHub]<br />
<br />
The '''dnd5elib''' library provides a collection of utility procedures that help simplify dealing with the D&D 5E Official Sheet. Some of the procedures in this library require '''chatsetattr''' to be installed in your game. This is a growing library, and currently only has a handful of routines. They are:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Procedure Name !! Notes<br />
|-<br />
| style="white-space:nowrap" | Lib5E_CheckDamageModifiers || This procedure can be used to evaluate vulnerabilities, resistances, and invulnerabilities on an NPC. After setting the --#target| parameters, pass the Lib5E_CheckDamageModifiers procedure a variable name (no reference information) and a damage type (i.e., fire, cold, bludgeoning, etc.), and the procedure will then create a string variable with with a name equal to the first parameter that you passed into the procedure. This variable will contain a string that can be included in a roll line (--=), in order to modify the roll as appropriate. For example, '''-->Lib5E_CheckDamageModifiers|ResistType;fire''' will check the current target character's attributes for "fire" and will either return an empty string (no references), "* 0 [Immune]" if the creature is immune, "\ 2 [Resistant]" if the creature is resistant, or "* 2 [Vulnerable]" if the creature is vulnerable to fire damage.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_DeductSpellSlot || Pass in a character_id and a slot level, and the script will expend one spell slot of that level, capping the value at 0 slots remaining. For Example '''<nowiki>-->Lib5E_DeductSpellSlot|@{selected|character_id};1</nowiki>''' to deduct a first level spell slot from the selected character.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_FindResource || Used to locate a resource value on a character. Pass in a character_id, a resource name, and two variable names. The procedure will check both repeating and non-repeating resources looking for a resource whose name matches what was passed in and return three variables. The first will be a string variable named for the 3rd parameter and contains the attribute name of the resource's "name" field. The second will be a string variable named after parameter 4 and contains the resource's value field attribute name, and the third variable is a Roll Variable, also named after the 4th parameter that contains the current resource value. Example: '''<nowiki>-->Lib5E_FindResource|@{selected|character_id};Crossbow bolts;ResName;ResValue</nowiki>''' will find "Crossbow bolts" as a resource on the character and return [&ResName] which is the name of the resource attribute, [&ResValue] which is the '''name of the attribute that stores the value''' and [$ResValue] which is the current numeric value of the resource.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Global_Attack_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Attack Modifiers (repeating_tohitmod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Bless" for 1d4 active and "Being Cool" for +2 active, I will get a return string " + 1d4 [Bless] + 2 [Being Cool]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Save_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Save Modifiers (repeating_savemod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Bless" for 1d4 active and "Being Cool" for +2 active, I will get a return string " + 1d4 [Bless] + 2 [Being Cool]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Skill_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Skill Modifiers (repeating_skillmod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Guidance" for 1d4 active and "Being Cool" for +2 active, I will get a return string " + 1d4 [Guidance] + 2 [Being Cool]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_AC_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Save Modifiers (repeating_savemod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Shield of Faith" with a value of 2 active, I will get a return string " + 2 [Shield of Faith]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Damage_Modifiers || Pass a character ID and TWO string variable to set the return value. The first string will be for normal damage, and the second will be the additional damage on a crit. This procedure will look through the Global Damage Modifiers (repeating_damagemod_*) for rows that are active (checked on the character sheet) and return two strings with the dice rolls and descriptions for them (for example, if I have "Sneak Attack" with a value of 1d6 normal and 1d6 critical damage active, I will get a return string " + 1d6 [Sneak Attack]" and another string of " + 1d6 [Sneak Attack CRIT]" that can be used in a dice rolls.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_DivineSmiteDice || Used to calculate the number of dice to be rolled for a paladin's Divine Smite. Pass a target token id, a spell slot level, and a string variable to be set to the dice roll amount based on the NPC_TYPE attribute of the target token. The returned variable will contain a dice roll (like "3d8" that can be used in a --= line)<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Character_Summary || Pass a character ID to outputs a mini character sheet, including clickable buttons for attacks, actions, legendary actions, etc. Will automatically detect a PC vs NPC and output the appropriate sections.<br />
|}<br />
<br />
Due to formatting issues with the Wiki, the library code has been moved to a [https://gist.github.com/kjaegers/52f6049ddd257f0a1288aca4bbde13c5 GITHUB GIT]. Please view the GIST in raw mode and copy the text and paste it into a handout called "ScriptCards Library dnd5elib" in your Roll20 Game.<br />
<br />
== What to Know if you are Coming from PowerCards ==<br />
<br />
''Note: This section is a work in progress.''<br />
<br />
While ScriptCards and PowerCard have very similar output goals, their internals and use are quite different. The table below summarizes some of the major differences between the scripts.<br />
<br />
::{| class="wikitable"<br />
|-<br />
! PowerCards !! ScriptCards <br />
|-<br />
| With a handful of exceptions, all lines in a PowerCard macro are intended to produce a line of output on the final card. || With ScriptCards, ONLY the <code>--+</code> and <code>--*</code> statement types produces output <br />
|-<br />
| PowerCards lines begin with two dashes (<code>--</code>) followed by a unique tag name for the line, followed by a vertical bar and the content for the line. || ScriptCards lines begin with two dashes (<code>--</code>) followed by a '''statement type identifier''', which is a single character that identifies the type of line to the interpreter. This is followed by a tag (frequently optional), a vertical bar, and the parameters for the statement being executed.<br />
|-<br />
| PowerCard macros are always processed top to bottom. Lines can be hidden so they don't output anything, but there is no looping or branching (--SkipTo looks like a branch, but it just hides all of the lines until the referenced label. || ScriptCards scripts support true branching, including direct branching (<code>--^</code>) and procedure branching (<code>--></code>) and (<code>--<</code>). Procedures support parameters and a call stack so procedures can be nested to call other procedures.<br />
|-<br />
| All lines in a PowerCards macro need to have unique tags because PowerCards builds the card as a single JavaScript object using the tag names to store what will be displayed. This is why repeated tag names always result in the last one being shown. || ScriptCards tags do not need to be unique, and in the case of many line types are optional.<br />
|-<br />
| PowerCards conditionals result in either showing or hiding the line they are on. || ScriptCards conditionals '''''only''''' support branching as the result of the comparison. This branching can be direct (a GOTO) or procedural (a GOSUB) '''''NOTE: As of version 1.2.0, ScriptCards also supports roll/string variable assignment as a result of conditional evaluation'''''<br />
|-<br />
| PowerCards relies on the Roll20 [[Quantum Roll]] server and inline rolls for all dice functions || ScriptCards includes its own dice roll parser, and '''''does not support''''' inline rolls.<br />
|-<br />
| PowerCards RollIDs (often mistaken for variables) are assigned by analyzing the results of an inline roll, and cannot be referenced in other rolls, so you can't roll a <code>1d4</code> and then roll a <code>1d20</code> and add the <code>1d4</code> result because all of the rolls happen on the chat server before PowerCards gets the macro text. || ScriptCards supports two types of variables: Roll Variables and String Variables. Because ScriptCards uses its own roll parser and is not dependent upon the chat server, rolls and their results can be used in other rolls, math functions, output, etc.<br />
|}<br />
<br />
== Example Scripts ==<br />
<br />
Below are some sample scripts that utilize the various statement types in ScriptCards:<br />
<br />
=== Divine Smite ===<br />
<br />
This script will prompt the user for a spell slot level to expend on a divine smite. It will check the target's npc_type to see if it is an Undead or Fiend, which adds an additional d8 to the smite roll.<br />
<br />
[[File:ScriptCards Divine Smite.png|Divine Smite Script Output]]<br />
<br />
<pre><br />
!scriptcard {{<br />
--#title|Divine Smite<br />
--=DiceCount|?{Spell Slot Level?|1|2|3|4|5|6|7|8|9} + 1<br />
--=IsFiendOrUndead|0<br />
--?"@{target|npc_type}" -inc fiend|>IsBoosted<br />
--?"@{target|npc_type}" -inc undead|>IsBoosted<br />
--=TotalDice|[$DiceCount] + [$IsFiendOrUndead]<br />
--=SmiteRoll|[$TotalDice]d8<br />
--#emoteText|@{selected|token_name} smites @{target|token_name}<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
--+Smite|deals [$SmiteRoll] radiant damage.<br />
--X|<br />
<br />
--:IsBoosted|<br />
--=IsFiendOrUndead|1<br />
--<|<br />
}}<br />
</pre><br />
<br />
==== How It Works ====<br />
<br />
The first line sets the "title" card parameter to "Divine Smite".<br />
<br />
Line 2 Shows a query to the user asking for the spell slot level, adds one and stores the value in the "DiceCount" Roll Variable. The query/dropdown is generated by the chat server prior to the script being executed.<br />
<br />
Line 3 defaults the "IsFiendOrUndead" Roll Variable to 0.<br />
<br />
Lines 4 and 5 compare the target's "npc_type" attribute (passed by the chat server as text) to see if they include either "undead" or "fiend". If true, the IsBoosted subroutine will be called. No parameters are passed to this subroutine.<br />
<br />
Line 6 sets the "TotalDice" variable to the base (DiceCount) number plus the IsFiendOrUndead number, which will be a 0 or a 1.<br />
<br />
Line 7 calculates "SmiteRoll" by rolling a number of d8 equal to the "TotalDice" value.<br />
<br />
Lines 8-10 set the parameters for the emote, which appears above the card content. By setting the sourceToken and the targetToken, their icons will appear in the emote surrounding the text describing the action.<br />
<br />
Line 11 is the only line that actually produces output on the card. It results in "Smite deals # radiant damage".<br />
<br />
Line 12 ends the script execution, preventing the script from continuing and running the subroutines out of context.<br />
<br />
Lines 14-16 are the IsBoosted subroutine, starting with the :IsBoosted label. The IsFiendOrUndead variable is set to 1, and a return from subroutine is executed.<br />
<br />
=== Magic Missile ===<br />
<br />
This script demonstrates using a loop and calling a subroutine to fire a number of missiles determine by the spell slot level used to cast the spell.<br />
<br />
[[File:ScriptCards_MagicMissile_Fixed.png|Magic Missile Script Output]]<br />
<br />
<pre><br />
!scriptcard {{ <br />
--#title|Magic Missile<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
--=MissileCount|?{Spell Slot Level?|1|2|3|4|5|6|7|8|9} + 2<br />
--=DisplayCount|1<br />
--=MissileDamage|0<br />
--#leftsub|Slot level ?{Spell Slot Level?}<br />
--#rightsub|Ranged Attack<br />
--#emoteText|Fred uses a level ?{Spell Slot Level?} spell slot to fire [$MissileCount.Total] missiles of magical force!<br />
--:MissileLoop|<br />
-->FireMissile|<br />
--=DisplayCount|[$DisplayCount] + 1<br />
--?[$DisplayCount] -le [$MissileCount]|MissileLoop<br />
--+Total|Total damage is [$MissileDamage]<br />
--X|<br />
<br />
--:FireMissile|<br />
--=ThisMissile|1d4 + 1<br />
--=MissileDamage|[$MissileDamage] + [$ThisMissile]<br />
--+Missile|[$DisplayCount.Total] Hits for [$ThisMissile] [b]force[/b] damage<br />
--<|<br />
}}<br />
</pre><br />
<br />
==== How It Works ====<br />
<br />
Lines 1-3 set the card title, the source token and the target token. Setting these tokens causes their icons/avatars to appear in the Emote section of the card.<br />
<br />
Line 4 asks the user what spell slot level they wish to use to cast magic missile. The number of missiles fired is equal to 2 plus the spell level, and this is stored in the MissileCount variable.<br />
<br />
Line 5 stores a 1 in the DisplayCount variable. This will be used to control the loop to determine the number of missiles fired and the missile number when displaying damage rolls.<br />
<br />
Line 6 initializes MissileDamage to 0<br />
<br />
Line 7 sets the left subtitle to the text "Slot Level #", where # is the spell slot level being used.<br />
<br />
Line 8 sets the right subtitle to the text "Ranged Attack".<br />
<br />
Line 9 sets the emoteText parameter with a description of the action, including the slot level and number of missiles fired.<br />
<br />
Line 10 is a label for the missile firing loop<br />
<br />
Line 11 Calls the "FireMissile" subroutine<br />
<br />
Line 12 increases the DisplayCount variable by 1<br />
<br />
Line 13 Checks to see if there are still missles to fire (DisplayCount <= MissileCount) and if so branches to MissileLoop<br />
<br />
Line 14 Displays the total damage dealt by the spell.<br />
<br />
Line 15 stops execution of the script to prevent out of context execution of the subroutine.<br />
<br />
Lines 76-21 are the FireMissile subroutine, beginning with the FireMissile label. The 1d4+1 is rolled and assigned to "ThisMissile". The result is added to the existing MissileDamage total, and a line for the current missile is displayed with the missile number and the damage for the missile.<br />
<br />
=== Longsword Attack ===<br />
<br />
This script demonstrates a standard 5E D&D melee weapon attack, including detection of misses, fumbles, hits, and critical hits. If installed, alterbars is used to decrement the target's BAR3 value by the damage dealt.<br />
<br />
[[File:ScriptCards Longsword.png|Longsword Script Output]]<br />
<br />
<pre><br />
!scriptcard {{<br />
--#title|Longsword<br />
--#leftsub|Melee Attack<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
--#emoteText|@{selected|token_name} attacks @{target|token_name}<br />
--=TargetAC|@{target|npc_ac}<br />
--?[$TargetAC.Total] -gt 0|DoneWithAC<br />
--=TargetAC|@{target|ac}<br />
--:DoneWithAC|<br />
--=AttackRoll|1d20 + @{selected|strength_mod} [STR] + @{selected|pb} [PROF]<br />
--+Attack|@{selected|token_name} rolls [$AttackRoll] vs AC [$TargetAC].<br />
--?[$AttackRoll.Base] -eq 20|Crit<br />
--?[$AttackRoll.Base] -eq 1|Fumble<br />
--?[$AttackRoll.Total] -ge [$TargetAC.Total]|Hit<br />
--+Miss|The attack missed.<br />
--^Final|<br />
<br />
--:Fumble|<br />
--+Fumble!|The attack went horribly wrong.<br />
--^Final|<br />
<br />
--:Hit|<br />
--=Damage|1d8 + @{selected|strength_mod} [STR]<br />
--+Hit!|The attack hit @{target|token_name} for [$Damage] slashing damage.<br />
--@alter|_target|@{target|token_id} _bar|3 _amount|-[$Damage]<br />
--^Final|<br />
<br />
--:Crit|<br />
--=Damage|1d8 + @{selected|strength_mod} [STR] + 1d8 [CRIT]<br />
--+Critical Hit!|The attack hit @{target|token_name} for [$Damage] slashing damage.<br />
--@alter|_target|@{target|token_id} _bar|3 _amount|-[$Damage]<br />
<br />
--:Final|<br />
}}<br />
</pre><br />
<br />
==== How it Works ====<br />
<br />
In lines 1-5, we set the title, subtitle, and emote text along with the tokens for the emote area.<br />
<br />
Lines 6-9 allow us to determine the AC of the target. On the 5E Roll20 sheet, NPCs armor class is stored in "npc_ac", while PCs armor class is in "ac". First we grab npc_ac and if it is zero, we check AC.<br />
<br />
Line 10 rolls the attack roll, rolling 1d20 and adding the attacker's strength modifier and proficiency bonus<br />
<br />
Line 11 displays the result of the attack roll on the card<br />
<br />
Lines 12-14 determine what kind of result the attack had. If the .Base value of the roll was 20, we branch to "Crit". If it was 1, we branch to "Fumble". If the .Total value of the roll was greater than or equal to the AC that was determined in Lines 6-9, we branch to Hit.<br />
<br />
Assuming we didn't branc anywhere, the result of the attack was a miss, so we display that on line 15 and then branch to "Final"<br />
<br />
This is followed by three branch segments, :Fumble, :Hit, and :Crit. A fumble displays a text message and branches to :Final.<br />
<br />
On a hit or a crit, we roll Damage (adding additional damage dice on a crit). We display a "Hit!" or "Critical Hit!" message and then make an API call to AlterBars, passing it the token id, bar we want to modify (3 in this case), and the amount we want to modify by the Damage value.<br />
<br />
=== Party Health Status ===<br />
<br />
This example calculates the current Hit Points remaining and HP percentage for each character and creates a color-coded display with the current party status.<br />
<br />
[[File:ScriptCards Party Health.png]]<br />
<br />
<pre><br />
!scriptcard {{<br />
--#title|Party Status<br />
--#titleCardBackground|#33CC33<br />
--#oddrowbackground|#bfee90<br />
--#evenrowbackground|#90eebf<br />
-->HealthCheck|@{Quej Grastra|character_id}<br />
-->HealthCheck|@{Brim Cheuto|character_id}<br />
-->HealthCheck|@{Odug Ututees|character_id}<br />
--X|End of card Execution<br />
<br />
--:HealthCheck|<br />
--=HealthPerc|[*[%1%]:hp] / [*[%1%]:hp^] * 100 \ 1<br />
--=HealthColor|000000<br />
--?[$HealthPerc.Total] -gt 50|HealthSkip<br />
--=HealthColor|FF0000<br />
--:HealthSkip|<br />
--+[*[%1%]:character_name]|has [#[$HealthColor.RollText]][*[%1%]:hp] of [*[%1%]:hp^][/#] HP [R]([$HealthPerc.Total]%)[/R]<br />
--<|End of HealthCheck<br />
}}<br />
</pre><br />
<br />
==== How it Works ====<br />
<br />
Lines 1-4, we set the card title, and set the title background and row background colors to shades of green.<br />
<br />
Lines 5-7 make gosub calls the the "HealthCheck" subroutine, passing in the character ID of each of the named characters (these are the names of the characters in my test game)<br />
<br />
Line 8 terminates the script execution.<br />
<br />
The remaining lines of the script are the HealthCheck subroutine, which works like this:<br />
<br />
Line 10 is the subroutine label (:HealthCheck)<br />
<br />
Line 11 uses the character id passed as a parameter and combines it with character attribute lookup *(...) to retrieve the value of "hp" and "hp<nowiki>^</nowiki>" for the character. The <nowiki>^</nowiki> character is used to specify that we want the MAX value for this attribute for the second call. We divide these two numbers and multiple by 100 to get a percentage. Finally, we use integer division by 1 to round the percentage and drop the decimals. The end result gets stored in the HealthPerc roll variable.<br />
<br />
Line 12 defaults to color of the health text to black<br />
<br />
Line 13 check to see if the health percentage is greater than 50. If so, it branches to HealthSkip, preventing the script from executing line 13.<br />
<br />
Line 14 sets the color of the health text to red<br />
<br />
Line 15 is the label that will be branched to from Line 13 to skip the red coloring<br />
<br />
Line 16 again uses character attribute substitution and the passed parameter value to output a display line containing the character name, the colorized health total, and the percentage value. The percentage is right-justified.<br />
<br />
Line 17 returns from the HealthCheck subroutine.<br />
<br />
=== Expanded Magic Missile Script ===<br />
<br />
This is the expanded and enhanced version of the Magic Missile script covered in {{yt|watch?v=u50xvNzS9Zk | this video}}. It includes visual and audio effects, checking and deducting spell slots, and applying damage using either Token-Mod or Alterbars.<br />
<br />
<pre><br />
!scriptcard {{ <br />
--#title|Magic Missile<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
<br />
-->GetAndCheckSlotInformation|<br />
<br />
--=MissileCount|[$SlotLevel] + 2<br />
--=DisplayCount|1<br />
--=MissileDamage|0<br />
--#leftsub|Slot level [$SlotLevel]<br />
--#rightsub|Ranged Attack<br />
--#emoteText|@{selected|character_name} uses a level [$SlotLevel.Total] spell slot to fire [$MissileCount.Total] missiles of magical force!<br />
<br />
--:MissileLoop|<br />
-->FireMissile|<br />
--=DisplayCount|[$DisplayCount] + 1<br />
--?[$DisplayCount] -le [$MissileCount]|MissileLoop<br />
--+Total|Total damage is [$MissileDamage]<br />
-->DeductSpellSlot|<br />
--#rightsub|Level [$SlotLevel] Left: [$SlotsRemaining] <br />
-->PlayEffects|none;burst-smoke;beam-magic;spell_01<br />
-->ApplyDamageTokenmod|@{target|token_id};3;-[$MissileDamage]<br />
-->ApplyDamageAlterbars|@{target|token_id};3;-[$MissileDamage]<br />
--X|<br />
<br />
--:FireMissile|<br />
--=ThisMissile|1d4 + 1<br />
--=MissileDamage|[$MissileDamage] + [$ThisMissile]<br />
--+Missile|[$DisplayCount.Total] Hits for [$ThisMissile] [b]force[/b] damage<br />
--<|<br />
<br />
--:GetAndCheckSlotInformation|<br />
--=SlotLevel|?{Spell Slot Level?|1|2|3|4|5|6|7|8|9}<br />
--=SlotsTotal|[*S:lvl[$SlotLevel]_slots_total]<br />
--=SlotsExpended|[*S:lvl[$SlotLevel]_slots_expended]<br />
--?[$SlotsExpended.Total] -ge [$SlotsTotal.Total]|NoSlotsLeft<br />
--<|<br />
<br />
--:NoSlotsLeft|<br />
--+|[*S:character_name] has no level [$SlotLevel.Total] spell slots available.<br />
--X|<br />
<br />
--:DeductSpellSlot|<br />
--=SlotsExpended|[$SlotsExpended] + 1<br />
--@setattr|_charid [*S:character_id] _lvl[$SlotLevel]_slots_expended|[$SlotsExpended] _silent<br />
--=SlotsRemaining|[$SlotsTotal] - [$SlotsExpended]<br />
--<|<br />
<br />
--:PlayEffects|Parameters are : source effect; target effect; line effect; sound effect<br />
--vtoken|@{selected|token_id} [%1%]<br />
--vtoken|@{target|token_id} [%2%]<br />
--vbetweentokens|@{selected|token_id} @{target|token_id} [%3%]<br />
--@roll20AM|_audio,play,nomenu|[%4%]<br />
--<|<br />
<br />
--:ApplyDamageTokenmod|Parameters are tokenid;bar#;amount<br />
--@token-mod|_ignore-selected _ids [%1%] _set bar[%2%]_value|[%3%]<br />
--<|<br />
<br />
--:ApplyDamageAlterbars|<br />
--@alter|_target|[%1%] _bar|[%2%] _amount|[%3%]<br />
--<|<br />
}}<br />
</pre><br />
<br />
[[Category:Featured articles]]</div>5004103https://wiki.roll20.net/Script:ScriptCardsScript:ScriptCards2021-10-05T16:43:15Z<p>5004103: /* dnd5elib */</p>
<hr />
<div>{{revdate}}<br />
== Introduction ==<br />
'''ScriptCards''' provides a script interpreter that can be used to create powerful macros that display the results of player/NPC actions, or display other information in a pleasing visual format in your game's chat window. The scripting language contains variables (both dice-roll (enhanced numerics) and strings) as well, conditionals, branching, subroutines with parameters, and a set of built-in functions to simplify working with Roll20 information.<br />
{{script overview<br />
|name=ScriptCards<br />
|author={{user profile|2365448|Kurt J.}}<br />
|code=<br />
|version=1.4.0e<br />
|lastmodified=2021-09-24}}<br />
ScriptCards is not game-system specific, and can be used with any system/sheet. Near the end of this Wiki there is a section set aside for libraries that can implement system-specific tasks, with the hope that enthusiasts playing particular systems will create and share utility functions that can be utilized by the wider community.<br />
<br />
The default display style for ScriptCards output is similar to the format used to document player and NPC abilities in Dungeons and Dragons 4th Edition, but does not have any system ties to D&D4E.<br />
<br />
Current OneClick Version : 1.4.0e<br />
<br />
Current Development Version : 1.4.4<br />
<br />
'''''<big>Critically Important: ScriptCards does not use/parse inline rolls. ScriptCards includes its own built-in dice roll parser to allow for the use of variables inside dice rolls. As of version 1.2.3, ScriptCards will now take inline rolls and substitute the total result value in statement strings, meaning that you can utilize inline rolls but ScriptCards will only see the result of the roll, and not parse the roll components itself.</big>'''''<br />
<br />
* {{fpl|9752053/ ScriptCards thread}}<br />
** {{fpl|10000297/ Scritpcard API Working and Sharing}}<br />
* https://github.com/kjaegers/ScriptCards/tree/main/ScriptCards_API - GitHub repository for source before the one-click version is updated.<br />
* {{yt.be|hyR7Jnq4mQM ScriptCards Intro}} 45min, Jan 2021<br />
* {{yt.be|u50xvNzS9Zk ScriptCards Magic Missile Deep Dive}} 39min, Feb 2021<br />
<br />
<br />
__TOC__<br />
=== Is ScriptCards Related to [[PowerCards]]? ===<br />
<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
Check the '''[[#What to Know if you are Coming from PowerCards|What to Know if you are Coming from PowerCards]]'''-section for a comparison table between the two scripts.<br />
<br />
== What is a ScriptCard Script ==<br />
<br />
A ScriptCard Script is text written into the chat window (either typed directly, pasted, or run via a macro) that will produce a card of information in the [[text Chat|chat window]]. A ScriptCard Script is composed of an [[API]] command: <code><nowiki>!scriptcard {{ }}</nowiki></code> enclosing any number of lines that determine the output that will be added to the card. At it simplest, the following macro:<br />
<br />
<pre>!scriptcard {{ }}</pre><br />
<br />
Will produce just a title card that displays “ScriptCards” as the name:<br />
<br />
[[File:Scriptcard blank.png]]<br />
<br />
Of course, this is just the simplest type of macro and isn’t very useful. In order to produce useful output, we need to include lines between the <code><nowiki>{{</nowiki></code> and <code><nowiki>}}</nowiki></code> that direct the API script as to what it should do.<br />
<br />
== Structure of a ScriptCard Line ==<br />
<br />
All ScriptCard lines begin with two dashes, followed by an ''statement identifier character'' that lets ScriptCards what type of line it is. There are several of these, and they are detailed in the next section. After the line type identifier, a Tag name 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.<br />
<br />
Following the Tag is a vertical bar, and then the content of the line itself. Again, each type of line might interpret this content differently.<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Identifier !! Statement Type !! Tag !! Content !! Notes<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--/</nowiki> || Comment || unused || unused || The <code>--/</code> 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--#</nowiki> || 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").<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--+</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--=</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--&</nowiki> || Assign String 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. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--@</nowiki> || 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 (i.e., [[TokenMod|!token-mod]], or [[ChatSetAttr|!setattr]], etc.)<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--:</nowiki> || 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<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--^</nowiki> || Branch To || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--></nowiki> || Call Procedure || 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<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--<</nowiki> || 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.<br />
|- <br />
| style="white-space:nowrap" | <nowiki>--?</nowiki> || Conditional Branch || Condition to be evaluated || True Branch Label<nowiki>|</nowiki>False Branch Label || The condition will be evaluated and execution will jump to one of the two indicated branches (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 included a semicolon separated list of parameters. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--s</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--l</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--v</nowiki> || 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+'''''<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--e</nowiki> || Echo to Chat || Name to send chat command as || Chat message to send || Variable substitution takes place on the tag and content.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--R</nowiki> || Retrieve Repeating Section Row information || "find", "first", or "next" || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--~</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--c</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--i</nowiki> || Information Request || User Prompt;Button Caption || InfoType;VariableName;ParameterText || See full documentation below.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--d</nowiki> || 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. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--%</nowiki> || 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. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--*</nowiki> || 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.<br />
|}<br />
<br />
== ScriptCard Statement Type Details ==<br />
The sections below detail the individual statement types supported by ScriptCards<br />
<br />
=== Comment (--/) ===<br />
<br />
A --/ statement is ignored by the ScriptCards parser. You can use this type of statement to add comments and informational text to your script. <br />
<br />
Example:<br />
<pre><br />
!script {{<br />
--/|Script Name : Fireball<br />
--/|Purpose : Allow the player to cast a fireball and blow stuff up!<br />
.<br />
.<br />
.<br />
}}<br />
</pre><br />
<br />
=== Set Parameter (--#) ===<br />
<br />
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.<br />
<br />
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.<br />
<br />
'''''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.'''''<br />
<br />
Examples:<br />
<pre><br />
--#title|Magic Missile<br />
--#leftsub|Level 1 Spell<br />
--#rightsub|Force Damage<br />
</pre><br />
<br />
The three examples above set the “title”, “leftsub”, and “rightsub” values for the card to the content value for the line. <br />
<br />
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.<br />
Settings Lines do not produce output lines on the card.<br />
<br />
The following settings are available (note that parameter names are ''not'' case sensitive):<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Name !! Effect/Use !! Default Value !! Type<br />
|-<br />
| 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<br />
|-<br />
| allowplaintextinrolls || If set to a non-zero value, plain character text in rolls will be copied to the roll text || 0 || Per-Line<br />
|-<br />
| bodyFontFace || Name of the font used in the card rows || Helvetica || Global<br />
|-<br />
| bodyFontSize || Size of the text in the card rows || 14px || Global<br />
|-<br />
| bodybackgroundimage || Specify an image (content for a CSS background-image tag) for the body area || none || Global<br />
|-<br />
| buttonBackground || Background color for buttons created with [button][/button] || #1C6EA4 || Per-Line<br />
|-<br />
| buttonBorderColor || Border (outline) color for buttons created with [button][/button] || #999999 || Per-Line<br />
|-<br />
| buttonFontFace || Font Family specifier for captions on buttons created with [button][/button] || Tahoma || Per-Line<br />
|-<br />
| buttonFontSize|| Text size for captions on buttons created with [button][/button] || x-small || Per-Line<br />
|-<br />
| buttonTextColor|| Text color of labels on buttons created with [button][/button] || #FFFFFF || Per-Line<br />
|-<br />
| 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<br />
|-<br />
| deferralcharacter || Changes the meta script deferral sequence to the specified value || ^ || Per-Line<br />
|-<br />
| diceFontColor|| Color of the dice created with the [d4] [d6], etc. formatting markers || #1C6EA4 || Per-Line<br />
|-<br />
| dicefontsize || Size of the dice created with the [d4] [d6], etc. formatting markers || 3.0em || Per-Line<br />
|-<br />
| 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<br />
|-<br />
| disablerollprocessing || If set to a non-zero value, --= lines will not process dice rolls strings || 0 || Per-Line<br />
|-<br />
| emoteBackground || Background color of the emote area || #f5f5ba || Global<br />
|-<br />
| emoteFont || Name of the font used in emote area (above the title of the output card) || Georgia || Global<br />
|-<br />
| emoteFontColor || Color of the font in the emote area || None (Empty) || Global<br />
|-<br />
| emoteFontSize || Size of the font used in the emote area || 14px || Global<br />
|-<br />
| emoteFontWeight || Font weight for the font in the emote area || bold|| Global<br />
|-<br />
| emoteState || If set to anything other than "visible", the emote portion of the card will not be displayed || visible || Global<br />
|-<br />
| emoteText || Text to display in the emote portion of the card || None (Empty) || Global<br />
|-<br />
| emotefont || Name of the font used in the emote text area || font-family: Georgia, serif; font-weight: bold; || Global<br />
|-<br />
| evenRowBackground || Hex code for the background color for even rows || #eeeeee || Per-Line<br />
|-<br />
| evenRowFontColor || Hex code for the text color for even rows || #000000 || Per-Line<br />
|-<br />
| evenrowbackgroundimage || Specify an image (content for a CSS background-image tag) for the even card rows || none || Per-Line<br />
|-<br />
| executionlimit || Maximum number of script lines the interpreter will try to execute. This prevents "infinite loop" sandbox crashes || 40000 || Global<br />
|-<br />
| hideCard || If set to any non-default value, the entire card output will be suppressed || 0 || Global<br />
|-<br />
| 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<br />
|-<br />
| 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<br />
|-<br />
| lineheight || Vertical size of each line on the output card || normal || Per-Line<br />
|-<br />
| nominmaxhighlight || If set to anything other than "0", rolls will not display crit/fumble/mixed highlight colors. || 0 || Per-Line<br />
|-<br />
| norollhighlight || If set to anything other than "0", rolls will not be formatted (plain numbers) but will still get a tooltip with details ('''''v1.3.6b+''''') || 0 || Per-Line<br />
|-<br />
| oddRowBackground || Hex code for the background color for even rows || #d0e4f5 || Per-Line <br />
|-<br />
| oddRowFontColor || Hex code for the text color for odd rows || #000000 || Per-Line<br />
|-<br />
| oddrowbackgroundimage || Specify an image (content for a CSS background-image tag) for the odd crd rows || none || Per-Line<br />
|-<br />
| reentrant || Used to name a script for rentrant button use || 0 || Global<br />
|-<br />
| 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)0 || Global<br />
|-<br />
| rollhilightlineheight || Determines the height of the hilight box placed around roll results ('''''1.4.2+''''') || 1.0em || Per-Line<br />
|-<br />
| roundUp || If set to a non-default value, integer division will round up instead of down || 0 || Per-Line<br />
|-<br />
| showfromfornonwhispers || If set to a non-zero value, will include the sender on cards that aren't whispered || 0 || Global<br />
|-<br />
| 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<br />
|-<br />
| subtitleFontColor || Color of the text in the subtitle areas || #FFFFFF || Global<br />
|-<br />
| subtitleFontFace || Name of the font used on the subtitle sections || Tahoma || Global<br />
|-<br />
| subtitleFontSize || Size of the subtitle font || 13px || Global<br />
|-<br />
| subtitleSeperator || The character(s) that will be placed between leftsub and rightsub || <nowiki>&#x2666</nowiki>; || Global<br />
|-<br />
| tableBorderRadius || CSS specifier for how rounded the borders of the output card are. Use "0px;" for square borders || 6px; || Global<br />
|-<br />
| tableShadow || CSS specifier for the drop shadow under the output card || 5px 3px 3px 0px #aaa; || Global<br />
|-<br />
| tablebgcolor || Background color of the whole card. '''''Normally not visible''''' || #EEEEEE || Global<br />
|-<br />
| tableborder || Color of the border that surrounds the whole card || 2px solid #000000; || Global<br />
|-<br />
| 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<br />
|-<br />
| timezone || IANA Specifier for the local time zone, used in system/date functions || merica/New_York || Per-Line<br />
|-<br />
| title || Text displayed in the title area of the card || ScriptCards || Global<br />
|-<br />
| titleCardBackground || A hex color code representing the background color of the title area. || #1c6ea4 || Global<br />
|-<br />
| titleFontColor || Color of the text on the card title || #FFFFFF || Global<br />
|-<br />
| titleFontFace || Name of the font used on the title area || Contrail One || Global<br />
|-<br />
| titleFontLineHeight || Line spacing on the title area || 1.2em || Global<br />
|-<br />
| titleFontSize || Size of the title font || 1.2em || Global<br />
|-<br />
| titlecardbackgroundimage || Specify an image (content for a CSS background-image tag) for the title card area || none || Global<br />
|-<br />
| titlecardbottomborder || Border CSS specifier for the bottom of the title card area || 2px solid #444444; || Global<br />
|-<br />
| titlecardgradient || If set to non-zero value, will place a vertical gradient on the title card area || 0 || Global<br />
|-<br />
| usehollowdice || If set to a non-zero value, the hollow/outline versions of the dice fonts will be used || 0 || Per-Line<br />
|-<br />
| whisper|| Comma separated list of who to whisper the output to. Use "gm" for [[GM|GMs]] and "self" for the sender || none || Global|}<br />
|}<br />
<br />
''Setting Lines do not produce output lines on the card''<br />
<br />
=== Direct Output (--+) ===<br />
<br />
A direct output line display 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.<br />
<br />
Examples of Direct Output lines:<br />
<pre><br />
--+Hello|World<br />
--+Attack|The monster rolls [$Attack] to hit!<br />
--+Damage|@{target|token_name} is hit for [$Damage] [#3333AA][b]frost[/b][/#] damage.<br />
</pre><br />
<br />
Direct Output lines support inline formatting, roll variable replacement, character attribute references, and procedure variables.<br />
<br />
=== GM Output (--*) ===<br />
<br />
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. <br />
<br />
Example:<br />
<pre><br />
--+PlayerLine|This line is shown on the public card<br />
--*GMLine|This line will only be shown to GMs, on a separate card.<br />
</pre><br />
<br />
=== Roll Variable Assignment (--=) ===<br />
<br />
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.<br />
<br />
'''''All components of a roll equation should be separated with spaces.'''''<br />
<br />
Examples:<br />
<pre><br />
--=MissileDamage|1d4 + 1<br />
--=Attack|1d20 + @{selected|strength_mod} [STR] + @{selected|pb} [PROF]<br />
</pre><br />
<br />
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. Text enclosed in square brackets ([]) is considered "flavor text" and will be added to the result text but does not impact the roll result.<br />
<br />
The following dice formats are supported:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Format Pattern !! Example !! Description<br />
|-<br />
| XdY || 3d8 || Simple format. Roll a Y-sided die X times<br />
|-<br />
| XdYkhZ || 2d20kh1 || Roll Y-sided die X times and keep the highest Z number of dice<br />
|-<br />
| XdYklZ || 4d6kl3 || Roll Y-sided die X times and keep the lowest Z number of dice <br />
|-<br />
| XdY>Z || 5d6>3 || Roll Y-sided die X times and count a 1 for each roll greater than Z <br />
|-<br />
| XdY<Z || 5d6<3 || Roll Y-sided die X times and count a 1 for each roll less than Z <br />
|}<br />
<br />
'''''Note: The dice formulae below are supported in the development version of ScriptCards and will be merged with the table above when activated on OneClick'''''<br />
::{| class="wikitable"<br />
|-<br />
! Format Pattern !! Example !! Description<br />
|-<br />
| 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<br />
|-<br />
| 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<br />
|-<br />
| 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)<br />
|-<br />
| 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<br />
|}<br />
<br />
The following operators are supported in a roll equation:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Operator !! Operation<br />
|-<br />
| + || Addition <br />
|-<br />
| - || Subtraction <br />
|-<br />
| * || Multiplication <br />
|-<br />
| / || Division <br />
|-<br />
| \ || Integer Division (Rounds down) <br />
|-<br />
| % || Modulo (Remainder of Divison)<br />
|}<br />
<br />
Roll Variables can be accessed at any time after they have been created by using the [$VariableName] format, with the following optional modifiers:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Modifier !! Meaning<br />
|-<br />
| No modifier || In a Direct Output Line (<nowiki>--+</nowiki>) 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<br />
|-<br />
| .Total || The end result of the roll equation as an unformatted number <br />
|-<br />
| .Base || The cumulative result of any dice rolled in the Roll Text (Numeric modifiers are not included) <br />
|-<br />
| .Ones || The number of dice in the roll that came up as 1s <br />
|-<br />
| .Aces || The number of dice in the roll that came up as the maximum number on the die <br />
|-<br />
| .Odds || The number of dice in the roll that came up with an odd number <br />
|-<br />
| .Evens || The number of dice in the roll that came up with an even number <br />
|-<br />
| .RollText || The raw text of the roll that was use to generate the results <br />
|-<br />
| .Text || A text representation of the results of the roll, including the numbers rolled for each die <br />
|-<br />
| .tableEntryText || The text portion of the result of a table roll<br />
|-<br />
| .tableEntryImgURL || The image source portion of the result of a table roll<br />
|-<br />
| .tableEntryValue || Numeric value of tableEntryText (via parseInt). If a non-numeric value, will be 0<br />
|-<br />
| .Raw || The total numeric result without any formatting, even if placed somewhere formatting would normally be done. <br />
|}<br />
<br />
Examples:<br />
<pre><br />
--+Total Damage|[$MissileDamage.Total] (roll was 1d4+1)<br />
--+Base Damage|[$MissileDamage.Base] (without the +1)<br />
--=Attack|1d20 + @{selected|strength_mod} [STR] + @{selected|pb} [PROF] + [$BlessBonus] [Bless]<br />
</pre><br />
<br />
In this case, 1d4 will be rolled and stored in “BlessBonus”, which can then be used in the Attack line.<br />
<br />
'''''Mathematical Functions in Roll Expressions '''''<br />
<br />
The ScriptCards roll parser works from left to right, always maintaining a current value and applying whatever comes next to the total. The following in-line functions to the roll parser. These are:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Expression !! Meaning<br />
|-<br />
| {ABS} || Absolute Value<br />
|-<br />
| {CEIL} || Ceiling value (round up to the next whole number)<br />
|-<br />
| {FLOOR} || Floor value (round down to the next whole number)<br />
|-<br />
| {ROUND} || Round value (round up if the decimal portion is greater than 0.5, otherwise round down)<br />
|-<br />
| {NEGATE} || Multiply the value by negative one.<br />
|-<br />
| {SQRT} || Take the square root of the running value. ('''''1.4.1+''''')<br />
|-<br />
| {SQUARE} || Square the running value. ('''''1.4.2+''''')<br />
|-<br />
| {CUBEROOT} || Take the cube root of the running value. ('''''1.4.2+''''')<br />
|-<br />
| {CUBE} || Cube the running value. ('''''1.4.2+''''')<br />
|-<br />
| {SIN} || Return the SIN of running value. ('''''1.4.2+''''')<br />
|-<br />
| {COS} || Return the COS of running value. ('''''1.4.2+''''')<br />
|-<br />
| {TAN} || Return the TAN of running value. ('''''1.4.2+''''')<br />
|-<br />
| {ASIN} || Return the ASIN of running value. ('''''1.4.2+''''')<br />
|-<br />
| {ACOS} || Return the ACOS of running value. ('''''1.4.2+''''')<br />
|-<br />
| {ATAN} || Return the ATAN of running value. ('''''1.4.2+''''')<br />
|}<br />
<br />
<br />
'''''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 <nowiki>[[ ]]</nowiki> 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.<br />
<br />
'''''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.<br />
<br />
'''Rolling on Rollable Tables'''<br />
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.<br />
<br />
''Roll Variable Lines do not produce output lines on the card.''<br />
<br />
=== String Variable Assignment (--&) ===<br />
<br />
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:<br />
<br />
<pre><br />
--&MyText|Hello<br />
</pre><br />
<br />
Here, we assign the text "Hello" to the string variable named MyText. You can also append text to a string variable by prefixing the content with a + sign:<br />
<br />
<pre><br />
--&MyText|+ World<br />
</pre><br />
<br />
If run after the statement above, MyText will now contain "Hello World".<br />
<br />
String variables can be referenced using the syntax [&variablename]<br />
<br />
=== Call API (--@) ===<br />
<br />
ScriptCards can use a Call API instruction to execute other API commands. The Tag contains the API 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 API command is executed.<br />
<br />
Examples:<br />
<pre><br />
--@eh|list<br />
--@alter|_target|@{target|token_id} _bar|3 _amount|-[$Damage]<br />
</pre><br />
<br />
In the first example above, the command <code>!eh list</code> will be executed, calling [[EncounterHelper]]. In the second, {{fpl|1216260/ AlterBars}} is called to modify a token's Bar 3 value.<br />
<br />
'''''Note:''''' When ScriptCards (or any API script) runs other API 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).<br />
<br />
See [[API:Script Index]] for more options.<br />
<br />
=== Branch Label (--:) ===<br />
<br />
A branch label defines a line in your code that can be reached by one of the branching instructions (<nowiki>--^</nowiki>, <nowiki>--></nowiki>, or <nowiki>--?</nowiki>). The Tag serves as the label name, and must be unique on the card.<br />
<br />
The vertical bar (|) separator must be present, but the content portion of the line is unused and can be treated as a comment.<br />
<br />
Examples:<br />
<pre><br />
--:MyLoop|<br />
--:CriticalHit|Will jump here if we roll a critical hit!<br />
</pre><br />
<br />
''A Branch Label line does not produce an output line on the card.''<br />
<br />
=== Branch (--^) === <br />
<br />
A Branch line 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.<br />
<br />
Examples:<br />
<pre><br />
--^MyLoop|Jumps to MyLoop<br />
--^SkipCrit|We didn't crit, so skip the Crit code<br />
</pre><br />
<br />
''A Branch line does not produce an output line on the card.''<br />
<br />
=== Call Procedure (-->) ===<br />
<br />
Similar to a branch, a Call Procedure (sometimes knows 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 (<nowiki>--<</nowiki>) 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 (;).<br />
<br />
Examples:<br />
<pre><br />
-->FixFormat|#3333FF;#999999<br />
</pre><br />
<br />
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%].<br />
<br />
=== Return (--<) ===<br />
<br />
A return instruction marks the end of a Gosub procedure. 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.<br />
<br />
Examples:<br />
<pre><br />
--<|<br />
--<|End of MySub<br />
</pre><br />
<br />
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.<br />
<br />
=== Conditional Statement (--?) ===<br />
<br />
A conditional statement contains some equation in the Tag that will be evaluated. '''''If any part of the comparison can/does contain a space, it needs to be surrounded by double quotes'''''<br />
<br />
Based on the true/false result of the evaluation, one of two execution paths will be taken. These execution paths are detailed in the content section of the statement. The "if true" path is specified first (directly after the vertical bar), and the "if false" path is specified after it, also separated by a vertical bar.<br />
<br />
Example:<br />
<pre><br />
--?[$AttackRoll.Total] -ge [$TargetAC]|Hit|Miss<br />
</pre><br />
<br />
'''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.'''<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Branch Format !! Meaning<br />
|-<br />
| Label || If just a label is specified, execution will branch to that label when the comparison is matched.<br />
|-<br />
| >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 <br />
|-<br />
| =VariableName || The roll variable "VariableName" will be assigned the value following a semicolon (ex: --?1 -eq 1|=Roll;1d20)<br />
|-<br />
| &VariableName || The string variable "VariableName" will be assigned the value following a semicolon (ex: --?1 -eq 1|&Result;Hit|&Result;Miss)<br />
|-<br />
| % or %! || The current for...next loop will perform the "next" action (%) or will break out (%!) <br />
|-<br />
| [ || Code block (see below)<br />
|}<br />
<br />
Examples:<br />
<pre><br />
--?[$AttackRoll.Base] -eq 20|CriticalHit<br />
--?[$AttackRoll.Base] -eq 1|>Fumble;@{selected|dexterity_mod}<br />
--?"@{target|npc_type}" -inc "undead"|&MonsterType;Undead|&MonsterType;Not Undead<br />
--?[$Attack.Total] >= [$ArmorClass]|>Hit|>Miss<br />
</pre><br />
<br />
In the first example, if the Base value of AttackRoll is a 20 (natural 20 on the die) execution will branch to the CriticalHit label.<br />
<br />
In the second example, 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%].<br />
<br />
The third example looks for the word "undead" in the npc_type attribute of the targeted character. If it exists in the text, the MonsterType string variable will be set to "Undead", otherwise it will be set to "Not Undead". <br />
<br />
The final example would call 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.<br />
<br />
''Text that does/may contain a space should be enclosed in double quotes.''<br />
<br />
The following comparison operators are available:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Comparator !! Meaning<br />
|-<br />
| -eq || Equal To <br />
|-<br />
| -eqi || Case insensitive Equal To <br />
|-<br />
| -ne || Not Equal To <br />
|-<br />
| -nei || Case insensitive Not Equal To <br />
|-<br />
| -gt || Greater Than <br />
|-<br />
| -ge || Greater Than or Equal To <br />
|-<br />
| -lt || Less Than <br />
|-<br />
| -le || Less Than or Equal To <br />
|-<br />
| -inc || Includes (text strings). <br />
|-<br />
| -ninc || Does Not Include (text strings). <br />
|}<br />
<br />
Multi-part conditionals are supported with -and and -or as separators. For example:<br />
<br />
<pre><br />
--?[$Attack.Total] -ge @{target|npc_ac} -and [$Attack.Base] -ne 20|HitButNotCrit<br />
</pre><br />
<br />
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):<br />
<br />
true AND false OR true<br />
<br />
Will be evaluated as true. The first two (true and false) will be false, but then false OR true will be true.<br />
<br />
Conversely:<br />
<br />
true or false and false<br />
<br />
Will be false, because the first true and false will evaluate to true, and then true and false will be false.<br />
<br />
'''CODE BLOCKS'''<br />
<br />
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.<br />
<br />
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:<br />
<br />
<pre><br />
!script {{<br />
--=Roll|1d2<br />
--+Roll|[$Roll]<br />
--?[$Roll.Total] -eq 2|[<br />
--&Value|Yep!<br />
--+|We are inside the TRUE portion of the block<br />
--]|[<br />
--&Value|Nope<br />
--+|We are inside the FALSE portion of the block<br />
--]|<br />
--+After|the blocks!<br />
--+Value|[&Value]<br />
}}<br />
</pre><br />
<br />
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 --]|. <br />
<br />
At this time, blocks cannot be nested, and can only be created as part of a conditional (--[ is not a valid statement type)<br />
<br />
''A conditional statement does not produce a line of output on the card.''<br />
<br />
=== Case Statement (--c) ===<br />
<br />
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 (:). Each match condition includes a branch label that will be used if the test value matches the item. 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:<br />
<br />
<pre><br />
!script {{<br />
--#title|Case Statement Testing<br />
--=Roll|1d4<br />
--C[$Roll.Total]|1:>One;[$Roll]|2:>Two;[$Roll]|3:>Three;[$Roll]|4:>Four;[$Roll]<br />
--X|<br />
<br />
--:One| --+Value|was One ([%1%]) --<|<br />
--:Two| --+Value|was Two ([%1%]) --<|<br />
--:Three| --+Value|was Three ([%1%]) --<|<br />
--:Four| --+Value|was Four ([%1%]) --<|<br />
}}<br />
</pre><br />
<br />
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 variable as a parameter.<br />
<br />
=== Save and Load (--s and --l) ===<br />
<br />
This statement pair is used to either store (--s) or load (--l) data from persistent storage. Items stored in persistent storage remain between card rolls and between Roll20 sessions. There are two types of data that can be stored: settings and roll variables. <br />
<br />
Examples:<br />
<br />
<pre><br />
--Ssettings|GreenStyle<br />
--Srollvariables|FirstCardVars<br />
</pre><br />
<br />
In this case, the tag for the statement determines what type of item is being saved (settings or rollvariables). When saving settings, all non-default settings are written to the named setting storage value. When Roll Variables are saved, all variables that currently exist will be saved to the named storage value.<br />
<br />
Loading stored items simply requires the same command with the --l statement type:<br />
<br />
<pre><br />
--Lsettings|GreenStyle<br />
--Lrollvariables|FirstCardVars<br />
</pre><br />
<br />
When loading settings, all stored settings will be applied to the current card settings. You can override settings by changing them after the load.<br />
<br />
When loading roll variables, the saved variables will be added to (or overwrite if they have the same name) any variables on the current card. This means it is safe to create roll variables before the load statement.<br />
<br />
'''Practical Uses'''<br />
The major intended use of persistent storage is for storing card formats for use in later scripts. For example, the following script:<br />
<br />
<pre><br />
!scriptcard {{<br />
--#titlecardbackground|#22CC22<br />
--#oddrowbackground|#cceecc<br />
--#evenrowbackground|#99ee99<br />
--Ssettings|@{selected|token_name}<br />
}}<br />
</pre><br />
<br />
Would save the titlecardbackground, oddrowbackground, and evenrowbackground settings to a saved list named after the selected token's name. When creating cards for that token to run later, you could include the line:<br />
<br />
<pre><br />
--Lsettings|@{selected|token_name}<br />
</pre><br />
<br />
To load all of the settings at once. By creating these setting sets for each character, you can specify a different color scheme for each character that can then be used in cards with a single formatting line.<br />
<br />
There is a supplemental ! command added to support saved settings:<br />
<br />
<pre><br />
!sc-liststoredsettings<br />
</pre><br />
<br />
Will produce a list of all stored setting names, with buttons to list the setting values stored in each group and a button to delete groups as needed.<br />
<br />
=== Visual Effects (--v) ===<br />
<br />
The --v statement can be used to create visual effects on the tabletop. The tag portion of the statement can be either "token" or "betweentokens". The content portion of the statement contains the required parameters for the effect generation, separated by spaces. If the effect is "none", no effect will be played. If any other value that doesn't match a Roll20 effect name will result in a burst-fire effect.<br />
<br />
For "token" effects, the parameters are the token id for the token the effect happens on, followed by the effect specifier.<br />
<br />
Example:<br />
<pre><br />
--vtoken|@{selected|token_id} burst-fire<br />
</pre><br />
<br />
For "betweentoken" effects, the parameters are the source token id, the target token id, and the effect specifier.<br />
<br />
Example:<br />
<pre><br />
--vbetweentokens|@{selected|token_id} @{target|token_id} beam-magic<br />
</pre><br />
<br />
'''''Version 1.2.8+'''''<br />
<br />
An additional effect specifier, "point" is available in 1.2.8+. This specifier allows you to create a visual effect at a designated X/Y pixel coordinate. Future updates will add custom-vfx support to this option. The parameters are the X and Y coordinates and the effect descriptor. As of version 1.2.9, you can also use custom effect specifiers with Point effects:<br />
<br />
<pre><br />
--vpoint|150 200 burst-fire<br />
</pre><br />
<br />
=== Echo to Chat (--e) ===<br />
<br />
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.<br />
<br />
Example:<br />
<pre><br />
--eThe Ghost|/em hovers around @{selected|character_name}... BOO!<br />
</pre><br />
<br />
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).<br />
<br />
'''''Whispering'''''<br />
<br />
You can use the echo statement to send a whisper, but there's a trick to it. If you execute this code here:<br />
<br />
<pre><br />
--eThe Ghost|/w ExamplePlayerName Boo.<br />
</pre><br />
<br />
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.<br />
<br />
So, in conclusion, it's best to use something like this when you're sending a whisper:<br />
<br />
<pre><br />
!script {{<br />
--#hidecard|1<br />
--&sender|The Ghost<br />
--&receiver|ExamplePlayerName<br />
--&message|Boo.<br />
--e[&sender]|/w [&receiver] [&message]<br />
--eScriptCards|/w gm **Whispered from [&sender] to [&receiver]:** [&message] <br />
}}<br />
</pre><br />
<br />
This will ensure that the message appears in your chat feed as well.<br />
<br />
=== Repeating Section Access (--R) ===<br />
<br />
ScriptCards (as of v0.0.13) supports accessing repeating section rows on a character sheet (for example: the attacks, the items, and the repeating resources) with the --R statement type. <br />
<br />
There are three basic commands you can use with --R, and they are specified by <br />
the tag used:<br />
<br />
<br />
'''''The "find" tag'''''<br />
<br />
An Rfind statement is used to search through a repeating field. Here is the general form of such a statement.<br />
<br />
<pre><br />
--Rfind|characterid;EntryName;SectionPrefix;SearchField<br />
</pre><br />
<br />
This is the most direct way to access a repeating section row. Supplying the character ID, followed by what you are looking for (Greatsword, for example), followed by the character sheet's section prefix (repeating_attack), followed by the field to check what you are searching for (atkname) will load the matching section (if found) into the script parsers memory. For example:<br />
<br />
<pre><br />
--Rfind|@{selected|character_id};Greatsword;repeating_attack;atkname<br />
</pre><br />
<br />
Will look at the character's "repeating_attack" section for an entry with an atkname value equal to "Greatsword". Similarly:<br />
<br />
<pre><br />
--Rfind|@{selected|character_id};Bite;repeating_npcaction;name<br />
</pre><br />
<br />
Will look for a "Bite" action on an NPC's action list.<br />
<br />
<br />
'''''The "first" tag'''''<br />
<br />
<pre><br />
--Rfirst|characterid;section prefix<br />
</pre><br />
<br />
This form of the --R command will look at all of the entries in the specified repeating section and load the first one into memory:<br />
<br />
<pre><br />
--Rfirst|@{selected|character_id};repeating_attack<br />
</pre><br />
<br />
Would load the character's first "repeating_attack" row into memory.<br />
<br />
<br />
'''''The "next" tag'''''<br />
<br />
<pre><br />
--Rnext|<br />
</pre><br />
<br />
No parameters are required for --Rnext, which loads the next entry in the list that was obtained with "first" into memory.<br />
<br />
<br />
'''''Section prefixes and how to use them'''''<br />
<br />
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 open [[D&D 5E by Roll20|this page]], and search for the phrase "repeating sections".<br />
<br />
<br />
'''''Additional information'''''<br />
<br />
However a row is obtained, it will be parsed to replace any attribute references (ie, @{level}) with the corresponding character attribute.<br />
<br />
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".<br />
<br />
You can reference repeating attribute data using the syntax [*R:attributename] syntax (similar to referencing standard character attributes).<br />
<br />
Here are some examples:<br />
<br />
Display the details of the "Greatsword" PC attack:<br />
<br />
<pre><br />
!script {{<br />
--Rfind|@{selected|character_id};Greatsword;repeating_attack;atkname<br />
--+Attack Name|[*R:atkname]<br />
--+Base Damage|[*R:dmgbase]<br />
}}<br />
</pre><br />
<br />
[[File:Scriptcards repeating greatsword.png|Repeating Greatsword Attack]]<br />
<br />
List all of the actions an NPC can take (just actions, not legendary, etc.)<br />
<br />
<pre><br />
!script {{<br />
--#title|NPC Actions<br />
--#leftsub|@{selected|token_name}<br />
--Rfirst|@{selected|character_id};repeating_npcaction<br />
--:DisplayLoop|<br />
--?"[*R:name]" -eq NoRepeatingAttributeLoaded|Done<br />
--+Action:|[*R:name] [*R:attack_damage] [*R:attack_damagetype]<br />
--?"[*R:attack_damage2]" -eq ""|NoSecondaryDamage<br />
--+ |[*R:attack_damage2] [*R:attack_damagetype2]<br />
--:NoSecondaryDamage|<br />
--Rnext|<br />
-->DisplayLoop| <br />
--:Done|<br />
}}<br />
</pre><br />
<br />
[[File:Scriptcards repeating npcactions.png]]<br />
<br />
In the script above, we get the "first" repeating_npcaction and display information about it. We then execute "next" and repeat until we run into "NoRepeatingAttributeLoaded".<br />
<br />
See the section named [[#Repeating Section Values|Repeating Section Values]] for more information.<br />
<br />
<br />
'''''Special debugging command: dump'''''<br />
<pre><br />
--Rdump|<br />
</pre><br />
<br />
The "dump" command will list all of the attributes ScriptCards knows about for the currently loaded repeating row to the API Console Log.<br />
<br />
=== Assign Variable to Built-In Function (--~) ===<br />
<br />
ScriptCards has the ability to run a function built into the API script and return the results to a variable. Some functions return roll variables, while others return strings. See the function table below for details. The format is:<br />
<br />
--~VariableName|function;param1;param2;param3;...<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Function Name !! Parameters !! Description<br />
|-<br />
| distance || token_A_ID;token_B_ID || Calculate the Chebyshev distance in grid units between two tokens. This is the measurement scheme D&D 4E/5E use for diagonal distance measurement<br />
|-<br />
| euclideandistance || token_A_ID;token_B_ID || Calculate the Euclidean distance between two tokens. This is essentially the Pythagorean theorem in action. Returns the result in grid units.<br />
|-<br />
| euclideanpixel || token_A_ID;token_B_ID || Calculate the Euclidean distance between two tokens and returns the result is pixels instead of grid units. <br />
|-<br />
| euclideanlong || token_A_ID;token_B_ID || 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 is calculated instead of before. More accurate over long distances. <br />
|-<br />
| manhattandistance || token_A_ID;token_B_ID || Also called "taxicabdistance" (which is an acceptable function name), this measures to how-many-over, how-many-up/down distance, disallowing diagonal movement.<br />
|-<br />
| getselected || none || 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 the first selected token, VariableName2 the second, etc.<br />
|}<br />
<br />
'''''Functions with Sub Functions'''''<br />
<br />
Most ScriptCards functions are grouped into set as sub functions. The table below lists the major functions and their sub functions.<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Function Name !! Sub Function !! Parameters !! Return Type !! Description<br />
|-<br />
| array || define || arrayname;value1;value2;... || none || Creates an array called "arrayname" and adds value1, value2, etc. to the array<br />
|-<br />
| array || sort || arrayname || none || Sorts the specified array in place in ascending order<br />
|-<br />
| array || add || arrayname;value1;value2;... || none || Adds value1, value2, ... to the existing array "arrayname"<br />
|-<br />
| array || remove || arrayname;value1;value2;... || none || Removes value1, value2, ... from the existing array "arrayname". Resets the array index to 0.<br />
|-<br />
| array || replace || arrayname;currentvalue;newvalue || none || Replaces all occurrences of "currentvalue" in "arayname" with "newvalue"<br />
|-<br />
| array || setatindex || arrayname;index;newvalue || none || Replaces the array item at index "index" with "newvalue"<br />
|-<br />
| array || getindex || arrayname || stringVariable || Retrieves the current index in "arrayname" and stores it in the supplied string variable<br />
|-<br />
| array || setindex || arrayname;newindex || none || Sets the current index in array "arrayname" to "newindex"<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| array || removeat || arrayname;indexposition || none || Removes the item at index "indexposition" from "arrayname". Resets the current array index to 0.<br />
|-<br />
| array || indexof || arrayname;searchvalue || stringVariable || Searches the array "arrayname" for and item with the value of "searchvalue" and, if found, returns the index of the first matching value or "ArrayError" if not found<br />
|-<br />
| array || getlength || arrayname || stringVariable || Returns the number of items in array "arrayname"<br />
|-<br />
| array || pagetokens || arrayname;tokenid;(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. 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.)<br />
|-<br />
| 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.<br />
|-<br />
| array || stringify || arrayname || stringVariable || Returns all of the items in "arrayname" as a string separated by semicolons (;)<br />
|-<br />
| array || fromstring || arrayname || delimiter;string || Creates an array from "string", splitting "string" on "delimiter" to separate the items<br />
|-<br />
| array || statusmarkers|| arrayname;tokenid || none|| Creates an array (arrayname) of the active statusmarkers (sometimes called Token Markers) for the specified tokenid<br />
|-<br />
| math || angle || math;angle;tokenid;tokenid|| rollVariable || Calculates the angle between two tokens and returns the value in degrees<br />
|-<br />
| math || ceil || math;ceil;value || rollVariable || Rounds '''value''' up to the next integer, dropping any decimal portion of the number<br />
|-<br />
| math || clamp || math;clamp;value;lowerBound;upperBound || rollVariable || Returns '''value''', but restricted to the range of '''loweBound''' and '''upperBound'''.<br />
|-<br />
| math || floor || math;floor;value || rollVariable || Rounds '''value''' down, dropping any decimal portion of the number<br />
|-<br />
| math || max || math;max;valueA;valueB || rollVariable || Returns the larger of '''valueA''' vs '''valueB'''<br />
|-<br />
| math || min || math;min;valueA;valueB || rollVariable || Returns the smaller of '''valueA''' vs '''valueB'''<br />
|-<br />
| math || round || math;round;value || rollVariable || Rounds '''value''' to the nearest integer<br />
|-<br />
| string || length || string;length;stringValue || rollVariable || Returns the length of '''stringValue''' in characters<br />
|-<br />
| string || before || string;before;searchText;stringValue || stringVariable || Searches '''stringValue''' for '''searchText''' and returns the portion of '''stringValue''' prior to that text<br />
|-<br />
| string || after || string;after;searchText;stringValue || stringVariable || Searches '''stringValue''' for '''searchText''' and returns the portion of '''stringValue''' after that text<br />
|-<br />
| string || left || string;left;count;stringValue || stringVariable || Returns the leftmost '''count''' characters of '''stringValue'''<br />
|-<br />
| string || right || string;right;count;stringValue || stringVariable || Returns the rightmost '''count''' characters of '''stringValue'''<br />
|-<br />
| string || replace || string;replace;searchText;replaceText;stringValue || stringVariable || Replaces '''searchText''' in '''stringValue''' with '''replaceText''' and returns the resulting string<br />
|-<br />
| string || replaceall || string;replace;searchText;replaceText;stringValue || stringVariable || Replaces all intances of '''searchText''' in '''stringValue''' with '''replaceText''' and returns the resulting string '''''Requires 1.2.9+'''''<br />
|-<br />
| string || trim || string;trim;stringValue || stringVariable || Removes leading and trailing spaces from stringValue and returns the result. <br />
|-<br />
| string || substring || string;substring;start;count;stringValue || stringVariable || Returns '''count''' characters starting at '''start''' from '''stringValue'''<br />
|-<br />
| 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.<br />
|-<br />
| string || tolowercase || string;tolowercase;stringValue || stringVariable || Converts the passed string to lower case and assigns to the passed variable name. <br />
|-<br />
| string || touppercase || string || stringVariable || Converts the passed string to upper case and assigns to the passed variable name. <br />
|-<br />
| 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. <br />
|-<br />
| 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.<br />
|-<br />
| 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'''.<br />
|-<br />
| turnorder || clear || none || none || Clears all entries from the {{Turn Tracker}}/Initiative<br />
|-<br />
| turnorder || addtoken || tokenid;trackervalue || none || Adds the token represented by "tokenid" to the initiative tracker with an initiavie value of "trackervalue"<br />
|-<br />
| turnorder || replacetoken || tokenid;trackervalue || none || Replaces the token represented by "tokenid" in the initiative tracker with an initiavie value of "trackervalue". Will add the token if it doesn't exist in the tracker.<br />
|-<br />
| turnorder || removetoken || tokenid || none || Removes the token represented by "tokenid" from the initiative tracker if it exists<br />
|-<br />
| turnorder || addcustom || textlabel;trackervalue || none || Add a custom text entry to the {{Turn Tracker}}/Initiative named "textlabel" with an initiative value of "trackervalue"<br />
|-<br />
| system || date || getdatetime || stringVariable || Returns the date time in the active timezone (see settings) <br />
|-<br />
| system || date || getdate || stringVariable || Returns the date in the active timezone (see settings) <br />
|-<br />
| system || date || gettime || stringVariable || Returns the time in the active timezone (see settings)<br />
|-<br />
| system || dumpvariables || "rolls", "string", or "array" || none || Dumps all of the defined variables of the indicated type to the console log<br />
|-<br />
| system || findability || system;findability;charactername;abilityname || stringVariable || Returns the object ID of the ability on the indicated character or "AbilityNotFound"<br />
|-<br />
|}<br />
<br />
Examples:<br />
<br />
<pre><br />
--~HowFarAway|distance;@{selected|token_id};@{target|token_id}<br />
</pre><br />
<br />
Returns the distance (Chebyshev) between the selected and target tokens and stores it in "HowFarAway".<br />
<br />
<pre><br />
--SelectedDudes|getselected<br />
</pre><br />
<br />
If 5 tokens were selected, 6 variables would be created: SelectedDudesCount (with a value of 5), SelectedDudes1, SelectedDudes2, SelectedDudes3, SelectedDudes4, SelectedDudes5.<br />
<br />
=== Information Request (--i) ===<br />
<br />
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.<br />
<br />
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.<br />
<br />
After the user has clicked the button and responded to the requests, ScriptCards will resume processing the script from where it left off.<br />
<br />
Here is an example “i” line:<br />
<br />
<pre><br />
--IScriptCards needs additional information to continue;Click to select a target and provide information|t;MyNewTarget;Missile1Target||q;MyNameIs;What is your name?<br />
</pre><br />
<br />
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.<br />
<br />
Supported information request types are “t” for target token, and “q” for query.<br />
<br />
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).<br />
<br />
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:<br />
<br />
<pre><br />
q;UserName;What is your name?|Fred|Bob|Sally|Nancy<br />
</pre><br />
<br />
Would have a dropdown menu with four choices.<br />
<br />
== Inline Formatting ==<br />
<br />
Inline formatting is processed on Direct Output lines only (--+ lines) and the following inline format markup is available:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Formatting Tags !! Description<br />
|-<br />
| [b]..[/b] || Bold the text between the markers <br />
|-<br />
| [i]..[/i] || Italicize the text between the markers <br />
|-<br />
| [u]..[/u] || Underline the text between the markers <br />
|-<br />
| [s]..[/s] || Strike-Thru the text between the markers <br />
|-<br />
| [c]..[/c] || Center alignment <br />
|-<br />
| [l]..[/l] || Left alignment <br />
|-<br />
| [r]..[/r] || Right alignment <br />
|-<br />
| [j]..[/j] || Full justification alignment <br />
|-<br />
| [#xxx]..[/#] or [#xxxxxx]..[/#] || Use a 3 or 6 digit hex code to colorize the text between the markers <br />
|-<br />
| [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, <code>[img width=128 height=128]</code> )<br />
|-<br />
| [button]caption::action[/button] || Create a button with the label "caption" that performs the action defined by "action". <br />
|-<br />
| [t] || Converted to HTML table tag. Text after the "t" will be included inside the tag (width, border, etc)<br />
|-<br />
| [/t] || Converted to HTML close table tag.<br />
|-<br />
| [tr] || Converted to HTML table row tag. Text after the "tr" will be included inside the tag<br />
|-<br />
| [/tr] || Converted to HTML close table row tag.<br />
|-<br />
| [td] || Converted to HTML table cell tag. Text after the "tr" will be included inside the tag<br />
|-<br />
| [/td] || Converted to HTML close table cell tag.<br />
|}<br />
<br />
== Variables ==<br />
<br />
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. While it is possible to assign both a string and a roll variable the same name, doing so will likely result in confusion when looking at the script later, so it is not recommended.<br />
<br />
String Variables are assigned with the --& statement and are referenced using [&variableName] notation.<br />
<br />
Roll Variables are assigned with the --= statement, and the assignment value is always processed by the ScriptCards Roll Processor (resolves dice rolls, etc.)<br />
<br />
There are a handful of variables assigned automatically when a ScriptCard is executed. These are all string variables, and are:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Variable !! Value<br />
|-<br />
| SendingPlayerID || Contains the object ID of the player that sent the macro<br />
|-<br />
| SendingPlayerName || Contains the display name of the player<br />
|-<br />
| SendingPlayerColor || Contains the color code associated with the player<br />
|-<br />
| SendingPlayerSpeakingAs || The contents of the "Speaking As" dropdown window<br />
|-<br />
| SendingPlayerIsGM || Contains 1 if the player is a GM, and 0 if the player is NOT a GM<br />
|}<br />
<br />
== Arrays ==<br />
<br />
Arrays are a special type of variable, and are managed by the function (<nowiki>--~</nowiki> command). All of the array function commands follow the same pattern:<br />
<br />
<pre>--~variableName|array;subcommand;arrayname;param1;param2;param3;...</pre><br />
<br />
Not all array commands return anything to "variableName". The function table above will specify the return type of the command if any.<br />
<br />
There are a couple of different ways to create an array:<br />
<br />
The '''define''' array subcommand creates (or recreates) an array and assigns it values - one for each included parameter after the array name. For example:<br />
<br />
<pre>--~|array;define;Fruits;mango;peach;strawberry;apricot;banana;apple</pre><br />
<br />
will create an array called '''Fruits''' with 6 elements in the order listed in the command (mango, peach, etc.)<br />
<br />
You can also use two other subcommands to create arrays based on tokens:<br />
<br />
<pre>--~Count|array;pagetokens;Everybondy;@{selected|token_id}</pre><br />
<br />
and<br />
<br />
<pre>--~Count|array;selectedtokens;Selected</pre><br />
<br />
In both cases, arrays of tokens will be created, and a string variable called "Count" will be set to the number of tokens in the array. The '''pagetokens''' command returns (by default) all of the tokens on the page that contains the token passed as the parameter after the array name. You can filter the tokens that "pagetokens" includes in the array by appending an optional parameter describing the type of token you are looking for:<br />
<br />
<pre>--~Count|array;pagetokens;Everybondy;@{selected|token_id};npc</pre><br />
<br />
Will return only tokens on the page that represent characters that do not have a ''controlledby'' parameter set. The available options are "all" (default), "char", "graphic", "pc", and "npc".<br />
<br />
The '''selectedtokens''' command returns an array with all of the tokens that were selected when the script was called.<br />
<br />
You can also use an arbitrary string to create an array, specifying a delimiter with the '''fromstring''' command:<br />
<br />
<pre><br />
--&names|Fred<br />
--&names|+,Sally<br />
--&names|+,Ted<br />
--&names|+,Joyce<br />
--~|array;fromstring;,;[&names]<br />
</pre><br />
<br />
The above example builds a comma-separated string and then uses "fromstring" to create an array with 4 elements from it, specifying the comma as the delimiter.<br />
<br />
Finally, you can use the '''statusmarkers''' command to create an array with one entry for each active status marker on a specified token:<br />
<br />
<pre>--~|array;statusmarkers;Conditions;@{selected|token_id}</pre><br />
<br />
will create an array with one entry for each status active on the selected token. The array elements will be the internal name of the status (if you are using custom status marker packs, the names will be specified in the marker pack).<br />
<br />
'''Traversing Arrays'''<br />
<br />
Each array keeps track of an internal index position (starting at 0). Several commands let you manage this index:<br />
<br />
*'''getindex''' returns the current index value<br />
*'''setindex''' sets the index to the specified location in the array<br />
*'''getlength''' returns the number of elements in the array<br />
*'''indexof''' returns the index location of the specified element<br />
<br />
Other commands let you retrieve values from the array:<br />
<br />
*'''getfirst''' sets the index to 0 and returns the value at that position<br />
*'''getnext''' advances the index by 1 and returns the new current value<br />
*'''getprevious''' reduces the index by 1 and returns the new current value<br />
*'''getlast''' sets the index to the last elements in the array and returns the new current value<br />
<br />
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.<br />
<br />
'''Manipulating Array Elements'''<br />
<br />
Several array commands deal with inserting, removing, and modifying elements:<br />
<br />
*'''add''' works just like define, except that it takes an existing array and adds elements to it based on the passed parameters<br />
*'''remove''' looks for items matching each passed parameter and removes them from the indicated array if they exist<br />
*'''removeat''' allows you to specify an index location in the array and remove the element at that position<br />
*'''replace''' searches an array for a value and replaces all occurrences of it with a new value (if found)<br />
*'''sort''' sorts the elements in the array in ascending order<br />
*'''strinfigy''' returns a string variable that includes each array element separated by semicolons (;) <br />
<br />
'''Referencing Array Elements'''<br />
<br />
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.<br />
<br />
<pre><br />
!script {{<br />
--~dummy|array;pagetokens;myarray;@{selected|token_id}<br />
--~count|array;getcount;myarray<br />
--+Total:|There are [&count] graphical objects on the page<br />
--~testvar|array;getfirst;myarray<br />
--:loop|<br />
--+Value|[*[&testvar]:character_name]<br />
--~testvar|array;getnext;myarray<br />
--?[&testvar] -ne ArrayError|loop<br />
--+Loop1|Is Done!<br />
}}<br />
</pre><br />
<br />
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:<br />
<br />
<pre><br />
!script {{<br />
--~dummy|array;pagetokens;myarray;@{selected|token_id}<br />
--~count|array;getcount;myarray<br />
--+Total:|There are [&count] graphical objects on the page<br />
--%loopCounter|1;[&count]<br />
--+Value|[*[@myarray([&loopCounter])]:character_name]<br />
--%|<br />
--+Loop|Is Done!<br />
}}<br />
</pre><br />
<br />
This line : <nowiki>--+Value|[*[@myarray([&loopCounter])]:character_name]</nowiki> uses [@arrayName(index)] format (inside a [*characterid:attribute] syntax) to perform the same task as running through the loop with the index.<br />
<br />
(Note: Additional examples are on the way...)<br />
<br />
== For...Next Loops ==<br />
<br />
For...Next loops in ScriptCards are supported with the with the --% statement type. A loop is defined by starting off with:<br />
<br />
<pre><br />
--%LoopCounter|<start>;<end>;[step]<br />
</pre><br />
<br />
The start and end values are required, while the step parameter is optional. If the step is omitted, it will be assumed to be 1. A string variable named after the line tag ("LoopCounter" in the case above) will be created and will hold the current iteration value for the loop. Here is a real example:<br />
<br />
<pre><br />
--%LoopCounter|1;10;1<br />
</pre><br />
<br />
This will begin a loop identified by "LoopCounter" that will start at 1, increasing by 1 each iteration (the step) until it has completed 10 executions.<br />
<br />
The "next" statement is simply <code>--%|</code>, with no tag or parameters. This indicates to ScriptCards that it should increment the counter and go back to the beginning of the loop. Extending the example above:<br />
<br />
<pre><br />
!script {{<br />
--%LoopCounter|1;10;1<br />
--=Roll|1d20<br />
--+Loop|Counter is [&LoopCounter], roll was [$Roll]<br />
--%|<br />
}}<br />
</pre><br />
<br />
The <code>--%!|</code> sequence will break out of the loop, no matter how many iterations are remaining.<br />
<br />
The % and %! character sequences can also be used as part of a 1.2.1+ non-branching conditional to continue or break the loop:<br />
<br />
<pre><br />
--?"X[&RollInto]X" -eq "XX"|%<br />
</pre><br />
<br />
In this example, if the string variable RollInfo is empty, the loop will return to the top and continue with the next iteration, while:<br />
<br />
<pre><br />
--?"X[&RollInto]X" -eq "XX"|%!<br />
</pre><br />
<br />
Would cause the whole loop to end if the condition were true.<br />
<br />
== Referencing ==<br />
<br />
=== Roll Variables===<br />
<br />
Roll Variables can be referenced from the content portion of any line type, and from the tag portion of conditional statements. The referenced value is replaced when the line is executed.<br />
<br />
There are several modifiers that can be used to reference parts of a roll:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Modifier !! Meaning<br />
|-<br />
| No modifier || In a Direct Output Line (<nowiki>--+</nowiki>), GM Output Line (<nowiki>--*</nowiki>), or String Assignement (<nowiki>--&</nowiki>), 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<br />
|-<br />
| .Total || The end result of the roll equation. Formatting rules for "No Modifier" apply based on line type. <br />
|-<br />
| .Raw || The total value of the roll variable without any formatting, no matter what kind of line the reference is used in.<br />
|-<br />
| .Base || The cumulative result of any dice rolled in the Roll Text (Numeric modifiers are not included) <br />
|-<br />
| .Ones || The number of dice in the roll that came up as 1s <br />
|-<br />
| .Aces || The number of dice in the roll that came up as the maximum number on the die <br />
|-<br />
| .Odds || The number of dice in the roll that came up with an odd number <br />
|-<br />
| .Evens || The number of dice in the roll that came up with an even number <br />
|-<br />
| .RollText || The raw text of the roll that was use to generate the results <br />
|-<br />
| .Text || A text representation of the results of the roll, including the numbers rolled for each die <br />
|-<br />
| .tableEntryText || The text portion of the result of a table roll<br />
|-<br />
| .tableEntryImgURL || The image source portion of the result of a table roll<br />
|-<br />
| .tableEntryValue || If the tableEntryText is purely numeric, will contain the numeric value<br />
|}<br />
<br />
=== String Variables ===<br />
<br />
To reference a string variable, use the notation [&variablename]. String variables can be referenced in direct output, roll variable assignment, and string variable assignment statements.<br />
<br />
=== Character/Token Attributes ===<br />
<br />
A character or token attribute can be referenced from content portion of any type of line and is substituted when the line is executed. The general format for referencing a character attribute is [*ID:attribute]. ID can be a token ID or a character ID (these start with a dash). Additionally if you have specified a sourceToken or targetToken, you can substitute "S" or "T" for the ID (for example [*S:npc_type] will retrieve the npc_type attribute from the source token.<br />
<br />
By default, all attribute references will be pulled from the '''''character''''' object that the ID represents (either directly or by being a Token ID that represents a character).<br />
<br />
Keep in mind, that if you want to access the "max" of a character attribute (for example, the max hit points), then you cannot trust the name that your roll20 character sheet shows you when you hover your mouse over the max hit points. For example, this reference will not work: [*S:hp_max]. Instead, you need to use this reference: [*S:hp^].<br />
<br />
If your ID refers to a token, token attributes can be accessed by preceding the attribute name with "t-", for example [*S:t-aura1_radius]. Supported token attributes are:<br />
<br />
{|<br />
| t-name || t-id || t-statusmarkers || t-bar1_value<br />
|-<br />
| t-bar1_max || t-bar2_value || t-bar2_max || t-bar3_value<br />
|-<br />
| t-bar3_max || t-top || t-left || t-width<br />
|-<br />
| t-height || t-rotation || t-layer || t-aura1_radius<br />
|-<br />
| t-aura1_color || t-aura2_radius || t-aura2_color || t-aura1_square<br />
|-<br />
| t-aura2_square || t-tint_color || t-light_radius || t-light_dimradius<br />
|-<br />
| t-light_angle || t-light_losangle || t-light_multiplier || t-light_otherplayers<br />
|-<br />
| t-light_hassight || t-flipv || t-fliph || t-controlledby<br />
|-<br />
| t-_cardid || t-_pageid || t-imgsrc || t-bar1_link<br />
|-<br />
| t-bar2_link || t-bar3_link || t-represents || t-layer<br />
|-<br />
| t-isdrawing || t-name || t-gmnotes || t-showname<br />
|-<br />
| t-showplayers_name || t-showplayers_bar1 || t-showplayers_bar2 || t-showplayers_bar3<br />
|-<br />
| t-showplayers_aura1 || t-showplayers_aura2 || t-playersedit_name || t-playersedit_bar1<br />
|-<br />
| t-playersedit_bar2 || t-playersedit_bar3 || t-playersedit_aura1 || t-playersedit_aura2<br />
|-<br />
| t-lastmove || t-adv_fow_view_distance || t-has_bright_light_vision || t-has_night_vision<br />
|-<br />
| t-night_vision_distance || t-emits_bright_light || t-bright_light_distance || t-emits_low_light<br />
|-<br />
| t-low_light_distance || t-has_limit_field_of_vision || t-limit_field_of_vision_center || t-limit_field_of_vision_total<br />
|-<br />
| t-has_limit_field_of_night_vision || t-limit_field_of_night_vision_center || t-limit_field_of_night_vision_total || t-has_directional_bright_light<br />
|-<br />
| t-directional_bright_light_center || t-directional_bright_light_total || t-has_directional_dim_light || t-directional_dim_light_center<br />
|-<br />
| t-directional_dim_light_total || t-lightColor || || |<br />
|}<br />
<br />
'''''It is important to note that some attributes names on tokens have corresponding attribute names on characters, which represent different values. For example, [*T:id] returns the character ID, while [*T:t-id] returns the token ID.'''''<br />
<br />
=== Subroutine Parameters ===<br />
<br />
When using a gosub statement (-->) or a conditional marked as a gosub (prefixing the label with a > character), you can pass any number of parameters separated by semicolons (;) that the code in the subroutine can utilize.<br />
<br />
Subroutine parameters are numbered starting at 1, and are accessed by using the notation [%number%], so the first parameter is [%1%], the second is [%2%], etc.<br />
<br />
Parameter substitution happens on all line types, and happens prior to character attribute references or roll variable substitution.<br />
<br />
=== Campaign Attribute ===<br />
You can retrieve properties of the API's Campaign object with the [*C:attributename] syntax. For example, [*C:playerpageid] will retrieve the current player ribbon page from the Campaign object.<br />
<br />
=== Page Attributes ===<br />
If you have set the '''activepage''' parameter, you can retrieve page-related properties with the [*P:attributename] syntax, including the page's UDL parameters.<br />
<br />
=== Repeating Section Values ===<br />
<br />
You can reference repeating attribute data using the syntax [*R:attributename] syntax (similar to referencing standard character attributes). The currently active repeating row information will be used to retrieve attribute values. You can also retrieve the full attribute name for a repeating row attribute by using the [*R>attributename] notation. This is useful to pass to things like chatsetattr.<br />
<br />
See the section named [[#Repeating Section Access (--R)|Repeating Section Access]] for more information.<br />
<br />
=== Array Elements ===<br />
After an array has been declared, the elements can be referenced with [@arrayName(index)]. Array indices start at 0.<br />
<br />
== Deferred Resolution for Meta Scripts ==<br />
<br />
As of 1.2.9, ScriptCards supports a deferral character for use when calling another API script with via the --@ statement, to defer processing of meta script references so they get processed prior to the sub-API call insted of prior to ScriptCards execution. To defer this processing for meta script (SelectManager, Fetch) by inserting a deferral character into the meta call. For example, if I want to have ScriptCards call TokenMod as if the token for "Quej Gr'stra" (yes, I let Roll20 name my test NPCs) I could use something like this:<br />
<br />
--@token-mod|{^& select Quej Gr'stra} _on showname<br />
<br />
The "^" in between { and & will prevent SelectManager from seeing the call when the ScriptCard script is processed, but the --@ statement will remove the deferral character so the command that will be sent by ScriptCards is:<br />
<br />
!token-mod {& select Quej Gr'stra} --on showname<br />
<br />
With the deferral character removed, SelectManager will see the {& select ...} and do its magic.<br />
<br />
While the default deferral character is "^", the deferral character is a setting that can be changed:<br />
<br />
--#deferralcharacter|%<br />
<br />
Will make % the deferral character for future --@ statements in the running script.<br />
<br />
There are currently three supported Meta script structures: {^&...} for SelectManager, @^(...) and *^(...) for fetch, where the ^ in the structures here represents the placement of the deferral character.<br />
<br />
== Arrays ==<br />
<br />
Arrays are a new data type introduced in version 1.1.12 of ScriptCards, and are manipulated with associated function (--~) commands.<br />
<br />
* Arrays are a lists of strings. Items in an array cannot contain the semi-colon (;) character, as that is used to separate parameters in the function code that deals with arrays.<br />
* Arrays are accessed via the --~ script command. In some cases, the value of the tag (variable name) for array commands is not used, and can be a dummy value or simply omitted. I have omitted them in the statements below.<br />
* All commands that DO return a value return string values, even if the content is numeric.<br />
* If a command returns a value and there is some sort of reason that it isn't an array value, you will get "ArrayError" in the return value. This can happen if you reach the end of an array while stepping through it, for example, so checking for "ArrayError" can serve as the end condition for a loop.<br />
* Each array keeps track of its current index, allowing you to step forward and backwards through arrays.<br />
* Any number of arrays can be defined.<br />
* Unlike string variables and roll variables, array variables cannot (currently) be referenced directly. It is necessary to use the function (--~) syntax to manipulate arrays and get values from them as strings for use in other parts of your script.<br />
<br />
<br />
== Reentrant Scripts ==<br />
<br />
Reentrant scripts allow you to create buttons in your script code that will re-execute the script at a given label within the code. If you set the reentrant setting (--#reentrant|somevalue) to a non-zero value, your setting and variable information will be preserved between executions. Reentrant script can be used to present menus or choices and then continue acting.<br />
<br />
Reentrant buttons are created with the [rbutton]Caption::ReentryLabel;Parameter[/rbutton] construct. The caption will be displayed on the generated button. ReentryLabel is the name of a label in your script that the button will jump to when clicked, and Parameter will be passed in as a string value called "reentryval".<br />
<br />
Example:<br />
<pre><br />
!script {{<br />
--#reentrant|testing<br />
--=Roll|1d20<br />
--+Roll|[$Roll]<br />
--&String|That was a [$Roll.Raw]!<br />
--~x|array;define;MyArray;Apple;Banana;Orange<br />
--+Try it|[rbutton]Hello!::EXEC_PC_SPELL;9[/rbutton]<br />
--X|<br />
<br />
--:EXEC_PC_SPELL|<br />
--+ReentryVal|[&reentryval]<br />
--+The value of Roll is|[$Roll]<br />
--+Value of String|[&String]<br />
--+Array|[@MyArray(0)]<br />
--X|<br />
}}<br />
</pre><br />
<br />
This script sets up some variables and then displays a button labeled "Hello!". If the user clicks the button, the script will be re-entered starting at the "EXEC_PC_SPELL", which will display the content of the variables from the original execution.<br />
<br />
'''''Note: This section needs to be expanded upon'''''<br />
<br />
== Procedure Libraries ==<br />
<br />
You can now create handouts in your game in Roll 20 with the name format "ScriptCards Library NAME", where name is a name you assign to the library. Library names are case sensitive. It is my hope that the more proficient ScriptCards scripters out there will provide procedure libraries (or procedures that can be included in libraries) for others to use to make their scripting life easier. Be they specific to a game system, or to a type of activity, I think a robust set of libraries that GMs could use to enhance their scripting capabilities would be very valuable to the community. Should such things begin to emerge, I’ll create a portion of the ScriptCards Wiki page to house them.<br />
<br />
To include one or more libraries in a script, use the +++libname+++ directive (does not need a -- line associated with it). Multiple library names can be specified by separating them with semicolons (i.e., +++General;dnd5elib;Colorize+++ would include three libraries (General, dnd5elib, and Colorize).<br />
<br />
Included libraries are separated from the main script code by the automatic inclusion of "--X|" before the first library is appended to the script, and all libraries are loaded at the end of the script before script processing takes place.<br />
<br />
Procedures and labels in libraries can be used just as if they were included in the body of your script. Note that this DOES mean that you could, technically, jump into a library with a direct branch (--^) or direct branch conditional, but I recommend using libraries to store reusable procedures.<br />
The Notes section of the library handout stores the library code, and is written just like any other ScriptCards code except:<br />
<br />
* They cannot use roll queries (?{Some Prompt:}) to get information from the user at execution time.<br />
* They cannot use @{} notation to access character and token information.<br />
<br />
Both of these limitation stem from the fact that Procedure Libraries are not processed by the chat server, which is what handles these items.<br />
<br />
Here is an example of handling damage modifications (resistance, vulnerability, and immunity) in D&D 5E with a library:<br />
<br />
<pre><br />
!script {{<br />
+++dnd5elib+++<br />
--#|Damage Modifiers Test<br />
--#targettoken|@{target|token_id}<br />
-->Lib5E_CheckDamageModifiers|ResistType;fire<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] fire damage<br />
<br />
-->Lib5E_CheckDamageModifiers|ResistType;cold<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] cold damage<br />
<br />
-->Lib5E_CheckDamageModifiers|ResistType;poison<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] poison damage<br />
<br />
-->Lib5E_CheckDamageModifiers|ResistType;acid<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] acid damage<br />
<br />
--X|<br />
}}<br />
</pre><br />
<br />
Library content (In a handout called “ScriptCards Library dnd5elib” NOTE: Paste into Notepad first and then paste into the handout in Roll20 to avoid bringing over HTML formatting from the web site):<br />
<br />
<pre><br />
--/|ScriptCards Library: dnd5elib version 0.0.1<br />
--/|Provides various utility procedures for D&D 5E games<br />
<br />
--/|Lib5E_CheckDamageModifiers handle damage resistance, vulnerability, and immunity. <br />
--/|Pass a string variable to be filled with a string to be appended to a dice roll and the damage type <br />
<br />
--:Lib5E_CheckDamageModifiers|damageVariableName;damageType<br />
--&[%1%]|<br />
--?"[*T:npc_vulnerabilities]" -inc "[%2%]"|>_Lib5E_IsVulnerable;[%1%]<br />
--?"[*T:npc_resistances]" -inc "[%2%]"|>_Lib5E_IsResistant;[%1%]<br />
--?"[*T:npc_immunities]" -inc "[%2%]"|>_Lib5E_IsImmune;[%1%]<br />
--<|<br />
<br />
--:_Lib5E_IsVulnerable| --&[%1%]| * 2 [Vulnerable] --<|<br />
--:_Lib5E_IsResistant| --&[%1%]| \ 2 [Resistant] --<|<br />
--:_Lib5E_IsImmune| --&[%1%]| * 0 [Immune] --<|<br />
</pre><br />
<br />
The idea is that the functions in the library create a string that can be appended to a roll to modify the output based on resistances, so you pass Lib5E_CheckDamageModifiers the name of the string variable you want to use and the damage type. The variable (ResistType in this case) will include either nothing, “* 2 [Vulnerable]”, “\ 2 [Resistant]”, or “* 0 [Immune]” which can be included in a roll assignment (--=) to modify the damage as appropriate. The order here might be important if an NPC is misconfigured to be both resistant and immune to the same damage type. Since immune is an absolute, having it last ensures that it will override resistant or vulnerable. A creature that is both vulnerable and resistant (again, misconfigured) will come back as resistant since that condition is checked after vulnerable.<br />
Some notes: I prefix my library labels with either “Lib5E_” or “_Lib5E_” as a clarity convention. This isn’t strictly necessary but you should be aware that if two libraries (or if your script and a library) define the same label, the last label defined will win. Since libraries are appended to the end of the script in the order you include them in the +++libname+++ directive, you can somewhat control this, but it is probably best to avoid re-declaring labels. <br />
<br />
In my case, items beginning with “Lib5E_” are intended to be called by scripts, while items beginning with “_Lib5E_” are intended to be used as subroutines by the “public” procedures. Of course, there is no reason you couldn’t call them directly.<br />
<br />
You might also note that I’ve included some library information in comment lines (--/|) at the top of the library. These are ignored by ScriptCards, and are a good way to convey requirements, parameters, usage information, etc.<br />
<br />
== Example Libraries ==<br />
<br />
=== dnd5elib ===<br />
<br />
[https://github.com/kjaegers/ScriptCards Download the dnd5elib Library from the ScriptCards GitHub]<br />
<br />
The '''dnd5elib''' library provides a collection of utility procedures that help simplify dealing with the D&D 5E Official Sheet. Some of the procedures in this library require '''chatsetattr''' to be installed in your game. This is a growing library, and currently only has a handful of routines. They are:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Procedure Name !! Notes<br />
|-<br />
| style="white-space:nowrap" | Lib5E_CheckDamageModifiers || This procedure can be used to evaluate vulnerabilities, resistances, and invulnerabilities on an NPC. After setting the --#target| parameters, pass the Lib5E_CheckDamageModifiers procedure a variable name (no reference information) and a damage type (i.e., fire, cold, bludgeoning, etc.), and the procedure will then create a string variable with with a name equal to the first parameter that you passed into the procedure. This variable will contain a string that can be included in a roll line (--=), in order to modify the roll as appropriate. For example, '''-->Lib5E_CheckDamageModifiers|ResistType;fire''' will check the current target character's attributes for "fire" and will either return an empty string (no references), "* 0 [Immune]" if the creature is immune, "\ 2 [Resistant]" if the creature is resistant, or "* 2 [Vulnerable]" if the creature is vulnerable to fire damage.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_DeductSpellSlot || Pass in a character_id and a slot level, and the script will expend one spell slot of that level, capping the value at 0 slots remaining. For Example '''<nowiki>-->Lib5E_DeductSpellSlot|@{selected|character_id};1</nowiki>''' to deduct a first level spell slot from the selected character.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_FindResource || Used to locate a resource value on a character. Pass in a character_id, a resource name, and two variable names. The procedure will check both repeating and non-repeating resources looking for a resource whose name matches what was passed in and return three variables. The first will be a string variable named for the 3rd parameter and contains the attribute name of the resource's "name" field. The second will be a string variable named after parameter 4 and contains the resource's value field attribute name, and the third variable is a Roll Variable, also named after the 4th parameter that contains the current resource value. Example: '''<nowiki>-->Lib5E_FindResource|@{selected|character_id};Crossbow bolts;ResName;ResValue</nowiki>''' will find "Crossbow bolts" as a resource on the character and return [&ResName] which is the name of the resource attribute, [&ResValue] which is the '''name of the attribute that stores the value''' and [$ResValue] which is the current numeric value of the resource.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Global_Attack_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Attack Modifiers (repeating_tohitmod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Bless" for 1d4 active and "Being Cool" for +2 active, I will get a return string " + 1d4 [Bless] + 2 [Being Cool]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Save_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Save Modifiers (repeating_savemod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Bless" for 1d4 active and "Being Cool" for +2 active, I will get a return string " + 1d4 [Bless] + 2 [Being Cool]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Skill_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Skill Modifiers (repeating_skillmod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Guidance" for 1d4 active and "Being Cool" for +2 active, I will get a return string " + 1d4 [Guidance] + 2 [Being Cool]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_AC_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Save Modifiers (repeating_savemod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Shield of Faith" with a value of 2 active, I will get a return string " + 2 [Shield of Faith]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Damage_Modifiers || Pass a character ID and TWO string variable to set the return value. The first string will be for normal damage, and the second will be the additional damage on a crit. This procedure will look through the Global Damage Modifiers (repeating_damagemod_*) for rows that are active (checked on the character sheet) and return two strings with the dice rolls and descriptions for them (for example, if I have "Sneak Attack" with a value of 1d6 normal and 1d6 critical damage active, I will get a return string " + 1d6 [Sneak Attack]" and another string of " + 1d6 [Sneak Attack CRIT]" that can be used in a dice rolls.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_DivineSmiteDice || Used to calculate the number of dice to be rolled for a paladin's Divine Smite. Pass a target token id, a spell slot level, and a string variable to be set to the dice roll amount based on the NPC_TYPE attribute of the target token. The returned variable will contain a dice roll (like "3d8" that can be used in a --= line)<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Character_Summary || Pass a character ID to outputs a mini character sheet, including clickable buttons for attacks, actions, legendary actions, etc. Will automatically detect a PC vs NPC and output the appropriate sections.<br />
|}<br />
<br />
Due to formatting issues with the Wiki, the library code has been moved to a [https://gist.github.com/kjaegers/52f6049ddd257f0a1288aca4bbde13c5 GITHUB GIT]. Please view the GIST in raw mode and copy the text and paste it into a handout called "ScriptCards Library dnd5elib" in your Roll20 Game.<br />
<br />
== What to Know if you are Coming from PowerCards ==<br />
<br />
''Note: This section is a work in progress.''<br />
<br />
While ScriptCards and PowerCard have very similar output goals, their internals and use are quite different. The table below summarizes some of the major differences between the scripts.<br />
<br />
::{| class="wikitable"<br />
|-<br />
! PowerCards !! ScriptCards <br />
|-<br />
| With a handful of exceptions, all lines in a PowerCard macro are intended to produce a line of output on the final card. || With ScriptCards, ONLY the <code>--+</code> and <code>--*</code> statement types produces output <br />
|-<br />
| PowerCards lines begin with two dashes (<code>--</code>) followed by a unique tag name for the line, followed by a vertical bar and the content for the line. || ScriptCards lines begin with two dashes (<code>--</code>) followed by a '''statement type identifier''', which is a single character that identifies the type of line to the interpreter. This is followed by a tag (frequently optional), a vertical bar, and the parameters for the statement being executed.<br />
|-<br />
| PowerCard macros are always processed top to bottom. Lines can be hidden so they don't output anything, but there is no looping or branching (--SkipTo looks like a branch, but it just hides all of the lines until the referenced label. || ScriptCards scripts support true branching, including direct branching (<code>--^</code>) and procedure branching (<code>--></code>) and (<code>--<</code>). Procedures support parameters and a call stack so procedures can be nested to call other procedures.<br />
|-<br />
| All lines in a PowerCards macro need to have unique tags because PowerCards builds the card as a single JavaScript object using the tag names to store what will be displayed. This is why repeated tag names always result in the last one being shown. || ScriptCards tags do not need to be unique, and in the case of many line types are optional.<br />
|-<br />
| PowerCards conditionals result in either showing or hiding the line they are on. || ScriptCards conditionals '''''only''''' support branching as the result of the comparison. This branching can be direct (a GOTO) or procedural (a GOSUB) '''''NOTE: As of version 1.2.0, ScriptCards also supports roll/string variable assignment as a result of conditional evaluation'''''<br />
|-<br />
| PowerCards relies on the Roll20 [[Quantum Roll]] server and inline rolls for all dice functions || ScriptCards includes its own dice roll parser, and '''''does not support''''' inline rolls.<br />
|-<br />
| PowerCards RollIDs (often mistaken for variables) are assigned by analyzing the results of an inline roll, and cannot be referenced in other rolls, so you can't roll a <code>1d4</code> and then roll a <code>1d20</code> and add the <code>1d4</code> result because all of the rolls happen on the chat server before PowerCards gets the macro text. || ScriptCards supports two types of variables: Roll Variables and String Variables. Because ScriptCards uses its own roll parser and is not dependent upon the chat server, rolls and their results can be used in other rolls, math functions, output, etc.<br />
|}<br />
<br />
== Example Scripts ==<br />
<br />
Below are some sample scripts that utilize the various statement types in ScriptCards:<br />
<br />
=== Divine Smite ===<br />
<br />
This script will prompt the user for a spell slot level to expend on a divine smite. It will check the target's npc_type to see if it is an Undead or Fiend, which adds an additional d8 to the smite roll.<br />
<br />
[[File:ScriptCards Divine Smite.png|Divine Smite Script Output]]<br />
<br />
<pre><br />
!scriptcard {{<br />
--#title|Divine Smite<br />
--=DiceCount|?{Spell Slot Level?|1|2|3|4|5|6|7|8|9} + 1<br />
--=IsFiendOrUndead|0<br />
--?"@{target|npc_type}" -inc fiend|>IsBoosted<br />
--?"@{target|npc_type}" -inc undead|>IsBoosted<br />
--=TotalDice|[$DiceCount] + [$IsFiendOrUndead]<br />
--=SmiteRoll|[$TotalDice]d8<br />
--#emoteText|@{selected|token_name} smites @{target|token_name}<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
--+Smite|deals [$SmiteRoll] radiant damage.<br />
--X|<br />
<br />
--:IsBoosted|<br />
--=IsFiendOrUndead|1<br />
--<|<br />
}}<br />
</pre><br />
<br />
==== How It Works ====<br />
<br />
The first line sets the "title" card parameter to "Divine Smite".<br />
<br />
Line 2 Shows a query to the user asking for the spell slot level, adds one and stores the value in the "DiceCount" Roll Variable. The query/dropdown is generated by the chat server prior to the script being executed.<br />
<br />
Line 3 defaults the "IsFiendOrUndead" Roll Variable to 0.<br />
<br />
Lines 4 and 5 compare the target's "npc_type" attribute (passed by the chat server as text) to see if they include either "undead" or "fiend". If true, the IsBoosted subroutine will be called. No parameters are passed to this subroutine.<br />
<br />
Line 6 sets the "TotalDice" variable to the base (DiceCount) number plus the IsFiendOrUndead number, which will be a 0 or a 1.<br />
<br />
Line 7 calculates "SmiteRoll" by rolling a number of d8 equal to the "TotalDice" value.<br />
<br />
Lines 8-10 set the parameters for the emote, which appears above the card content. By setting the sourceToken and the targetToken, their icons will appear in the emote surrounding the text describing the action.<br />
<br />
Line 11 is the only line that actually produces output on the card. It results in "Smite deals # radiant damage".<br />
<br />
Line 12 ends the script execution, preventing the script from continuing and running the subroutines out of context.<br />
<br />
Lines 14-16 are the IsBoosted subroutine, starting with the :IsBoosted label. The IsFiendOrUndead variable is set to 1, and a return from subroutine is executed.<br />
<br />
=== Magic Missile ===<br />
<br />
This script demonstrates using a loop and calling a subroutine to fire a number of missiles determine by the spell slot level used to cast the spell.<br />
<br />
[[File:ScriptCards_MagicMissile_Fixed.png|Magic Missile Script Output]]<br />
<br />
<pre><br />
!scriptcard {{ <br />
--#title|Magic Missile<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
--=MissileCount|?{Spell Slot Level?|1|2|3|4|5|6|7|8|9} + 2<br />
--=DisplayCount|1<br />
--=MissileDamage|0<br />
--#leftsub|Slot level ?{Spell Slot Level?}<br />
--#rightsub|Ranged Attack<br />
--#emoteText|Fred uses a level ?{Spell Slot Level?} spell slot to fire [$MissileCount.Total] missiles of magical force!<br />
--:MissileLoop|<br />
-->FireMissile|<br />
--=DisplayCount|[$DisplayCount] + 1<br />
--?[$DisplayCount] -le [$MissileCount]|MissileLoop<br />
--+Total|Total damage is [$MissileDamage]<br />
--X|<br />
<br />
--:FireMissile|<br />
--=ThisMissile|1d4 + 1<br />
--=MissileDamage|[$MissileDamage] + [$ThisMissile]<br />
--+Missile|[$DisplayCount.Total] Hits for [$ThisMissile] [b]force[/b] damage<br />
--<|<br />
}}<br />
</pre><br />
<br />
==== How It Works ====<br />
<br />
Lines 1-3 set the card title, the source token and the target token. Setting these tokens causes their icons/avatars to appear in the Emote section of the card.<br />
<br />
Line 4 asks the user what spell slot level they wish to use to cast magic missile. The number of missiles fired is equal to 2 plus the spell level, and this is stored in the MissileCount variable.<br />
<br />
Line 5 stores a 1 in the DisplayCount variable. This will be used to control the loop to determine the number of missiles fired and the missile number when displaying damage rolls.<br />
<br />
Line 6 initializes MissileDamage to 0<br />
<br />
Line 7 sets the left subtitle to the text "Slot Level #", where # is the spell slot level being used.<br />
<br />
Line 8 sets the right subtitle to the text "Ranged Attack".<br />
<br />
Line 9 sets the emoteText parameter with a description of the action, including the slot level and number of missiles fired.<br />
<br />
Line 10 is a label for the missile firing loop<br />
<br />
Line 11 Calls the "FireMissile" subroutine<br />
<br />
Line 12 increases the DisplayCount variable by 1<br />
<br />
Line 13 Checks to see if there are still missles to fire (DisplayCount <= MissileCount) and if so branches to MissileLoop<br />
<br />
Line 14 Displays the total damage dealt by the spell.<br />
<br />
Line 15 stops execution of the script to prevent out of context execution of the subroutine.<br />
<br />
Lines 76-21 are the FireMissile subroutine, beginning with the FireMissile label. The 1d4+1 is rolled and assigned to "ThisMissile". The result is added to the existing MissileDamage total, and a line for the current missile is displayed with the missile number and the damage for the missile.<br />
<br />
=== Longsword Attack ===<br />
<br />
This script demonstrates a standard 5E D&D melee weapon attack, including detection of misses, fumbles, hits, and critical hits. If installed, alterbars is used to decrement the target's BAR3 value by the damage dealt.<br />
<br />
[[File:ScriptCards Longsword.png|Longsword Script Output]]<br />
<br />
<pre><br />
!scriptcard {{<br />
--#title|Longsword<br />
--#leftsub|Melee Attack<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
--#emoteText|@{selected|token_name} attacks @{target|token_name}<br />
--=TargetAC|@{target|npc_ac}<br />
--?[$TargetAC.Total] -gt 0|DoneWithAC<br />
--=TargetAC|@{target|ac}<br />
--:DoneWithAC|<br />
--=AttackRoll|1d20 + @{selected|strength_mod} [STR] + @{selected|pb} [PROF]<br />
--+Attack|@{selected|token_name} rolls [$AttackRoll] vs AC [$TargetAC].<br />
--?[$AttackRoll.Base] -eq 20|Crit<br />
--?[$AttackRoll.Base] -eq 1|Fumble<br />
--?[$AttackRoll.Total] -ge [$TargetAC.Total]|Hit<br />
--+Miss|The attack missed.<br />
--^Final|<br />
<br />
--:Fumble|<br />
--+Fumble!|The attack went horribly wrong.<br />
--^Final|<br />
<br />
--:Hit|<br />
--=Damage|1d8 + @{selected|strength_mod} [STR]<br />
--+Hit!|The attack hit @{target|token_name} for [$Damage] slashing damage.<br />
--@alter|_target|@{target|token_id} _bar|3 _amount|-[$Damage]<br />
--^Final|<br />
<br />
--:Crit|<br />
--=Damage|1d8 + @{selected|strength_mod} [STR] + 1d8 [CRIT]<br />
--+Critical Hit!|The attack hit @{target|token_name} for [$Damage] slashing damage.<br />
--@alter|_target|@{target|token_id} _bar|3 _amount|-[$Damage]<br />
<br />
--:Final|<br />
}}<br />
</pre><br />
<br />
==== How it Works ====<br />
<br />
In lines 1-5, we set the title, subtitle, and emote text along with the tokens for the emote area.<br />
<br />
Lines 6-9 allow us to determine the AC of the target. On the 5E Roll20 sheet, NPCs armor class is stored in "npc_ac", while PCs armor class is in "ac". First we grab npc_ac and if it is zero, we check AC.<br />
<br />
Line 10 rolls the attack roll, rolling 1d20 and adding the attacker's strength modifier and proficiency bonus<br />
<br />
Line 11 displays the result of the attack roll on the card<br />
<br />
Lines 12-14 determine what kind of result the attack had. If the .Base value of the roll was 20, we branch to "Crit". If it was 1, we branch to "Fumble". If the .Total value of the roll was greater than or equal to the AC that was determined in Lines 6-9, we branch to Hit.<br />
<br />
Assuming we didn't branc anywhere, the result of the attack was a miss, so we display that on line 15 and then branch to "Final"<br />
<br />
This is followed by three branch segments, :Fumble, :Hit, and :Crit. A fumble displays a text message and branches to :Final.<br />
<br />
On a hit or a crit, we roll Damage (adding additional damage dice on a crit). We display a "Hit!" or "Critical Hit!" message and then make an API call to AlterBars, passing it the token id, bar we want to modify (3 in this case), and the amount we want to modify by the Damage value.<br />
<br />
=== Party Health Status ===<br />
<br />
This example calculates the current Hit Points remaining and HP percentage for each character and creates a color-coded display with the current party status.<br />
<br />
[[File:ScriptCards Party Health.png]]<br />
<br />
<pre><br />
!scriptcard {{<br />
--#title|Party Status<br />
--#titleCardBackground|#33CC33<br />
--#oddrowbackground|#bfee90<br />
--#evenrowbackground|#90eebf<br />
-->HealthCheck|@{Quej Grastra|character_id}<br />
-->HealthCheck|@{Brim Cheuto|character_id}<br />
-->HealthCheck|@{Odug Ututees|character_id}<br />
--X|End of card Execution<br />
<br />
--:HealthCheck|<br />
--=HealthPerc|[*[%1%]:hp] / [*[%1%]:hp^] * 100 \ 1<br />
--=HealthColor|000000<br />
--?[$HealthPerc.Total] -gt 50|HealthSkip<br />
--=HealthColor|FF0000<br />
--:HealthSkip|<br />
--+[*[%1%]:character_name]|has [#[$HealthColor.RollText]][*[%1%]:hp] of [*[%1%]:hp^][/#] HP [R]([$HealthPerc.Total]%)[/R]<br />
--<|End of HealthCheck<br />
}}<br />
</pre><br />
<br />
==== How it Works ====<br />
<br />
Lines 1-4, we set the card title, and set the title background and row background colors to shades of green.<br />
<br />
Lines 5-7 make gosub calls the the "HealthCheck" subroutine, passing in the character ID of each of the named characters (these are the names of the characters in my test game)<br />
<br />
Line 8 terminates the script execution.<br />
<br />
The remaining lines of the script are the HealthCheck subroutine, which works like this:<br />
<br />
Line 10 is the subroutine label (:HealthCheck)<br />
<br />
Line 11 uses the character id passed as a parameter and combines it with character attribute lookup *(...) to retrieve the value of "hp" and "hp<nowiki>^</nowiki>" for the character. The <nowiki>^</nowiki> character is used to specify that we want the MAX value for this attribute for the second call. We divide these two numbers and multiple by 100 to get a percentage. Finally, we use integer division by 1 to round the percentage and drop the decimals. The end result gets stored in the HealthPerc roll variable.<br />
<br />
Line 12 defaults to color of the health text to black<br />
<br />
Line 13 check to see if the health percentage is greater than 50. If so, it branches to HealthSkip, preventing the script from executing line 13.<br />
<br />
Line 14 sets the color of the health text to red<br />
<br />
Line 15 is the label that will be branched to from Line 13 to skip the red coloring<br />
<br />
Line 16 again uses character attribute substitution and the passed parameter value to output a display line containing the character name, the colorized health total, and the percentage value. The percentage is right-justified.<br />
<br />
Line 17 returns from the HealthCheck subroutine.<br />
<br />
=== Expanded Magic Missile Script ===<br />
<br />
This is the expanded and enhanced version of the Magic Missile script covered in {{yt|watch?v=u50xvNzS9Zk | this video}}. It includes visual and audio effects, checking and deducting spell slots, and applying damage using either Token-Mod or Alterbars.<br />
<br />
<pre><br />
!scriptcard {{ <br />
--#title|Magic Missile<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
<br />
-->GetAndCheckSlotInformation|<br />
<br />
--=MissileCount|[$SlotLevel] + 2<br />
--=DisplayCount|1<br />
--=MissileDamage|0<br />
--#leftsub|Slot level [$SlotLevel]<br />
--#rightsub|Ranged Attack<br />
--#emoteText|@{selected|character_name} uses a level [$SlotLevel.Total] spell slot to fire [$MissileCount.Total] missiles of magical force!<br />
<br />
--:MissileLoop|<br />
-->FireMissile|<br />
--=DisplayCount|[$DisplayCount] + 1<br />
--?[$DisplayCount] -le [$MissileCount]|MissileLoop<br />
--+Total|Total damage is [$MissileDamage]<br />
-->DeductSpellSlot|<br />
--#rightsub|Level [$SlotLevel] Left: [$SlotsRemaining] <br />
-->PlayEffects|none;burst-smoke;beam-magic;spell_01<br />
-->ApplyDamageTokenmod|@{target|token_id};3;-[$MissileDamage]<br />
-->ApplyDamageAlterbars|@{target|token_id};3;-[$MissileDamage]<br />
--X|<br />
<br />
--:FireMissile|<br />
--=ThisMissile|1d4 + 1<br />
--=MissileDamage|[$MissileDamage] + [$ThisMissile]<br />
--+Missile|[$DisplayCount.Total] Hits for [$ThisMissile] [b]force[/b] damage<br />
--<|<br />
<br />
--:GetAndCheckSlotInformation|<br />
--=SlotLevel|?{Spell Slot Level?|1|2|3|4|5|6|7|8|9}<br />
--=SlotsTotal|[*S:lvl[$SlotLevel]_slots_total]<br />
--=SlotsExpended|[*S:lvl[$SlotLevel]_slots_expended]<br />
--?[$SlotsExpended.Total] -ge [$SlotsTotal.Total]|NoSlotsLeft<br />
--<|<br />
<br />
--:NoSlotsLeft|<br />
--+|[*S:character_name] has no level [$SlotLevel.Total] spell slots available.<br />
--X|<br />
<br />
--:DeductSpellSlot|<br />
--=SlotsExpended|[$SlotsExpended] + 1<br />
--@setattr|_charid [*S:character_id] _lvl[$SlotLevel]_slots_expended|[$SlotsExpended] _silent<br />
--=SlotsRemaining|[$SlotsTotal] - [$SlotsExpended]<br />
--<|<br />
<br />
--:PlayEffects|Parameters are : source effect; target effect; line effect; sound effect<br />
--vtoken|@{selected|token_id} [%1%]<br />
--vtoken|@{target|token_id} [%2%]<br />
--vbetweentokens|@{selected|token_id} @{target|token_id} [%3%]<br />
--@roll20AM|_audio,play,nomenu|[%4%]<br />
--<|<br />
<br />
--:ApplyDamageTokenmod|Parameters are tokenid;bar#;amount<br />
--@token-mod|_ignore-selected _ids [%1%] _set bar[%2%]_value|[%3%]<br />
--<|<br />
<br />
--:ApplyDamageAlterbars|<br />
--@alter|_target|[%1%] _bar|[%2%] _amount|[%3%]<br />
--<|<br />
}}<br />
</pre><br />
<br />
[[Category:Featured articles]]</div>5004103https://wiki.roll20.net/D%26D_5E_by_Roll20D&D 5E by Roll202021-10-01T16:28:54Z<p>5004103: /* Directly Referencing Attributes */</p>
<hr />
<div>{{revdate}}{{HCbox|{{hc|360037773573-5th-Edition-OGL-by-Roll20 D&D 5E by Roll20}} }}<br />
[[File:5E OGL Sheet Core v2.6.png|500px|thumb|right|The '''D&D 5E by Roll20''' Character Sheet]]<br />
<br />
This is the community-driven documentation for the '''[[5E|D&D 5E]] by Roll20''' character sheet. Previously the sheet was known as the '''"5th Edition OGL Sheet"''' or just the '''"OGL Sheet"'''.<br />
<br />
=The Basics=<br />
This page is a ''[[Community Wiki]]'' guide to the Official D&D 5th Edition character sheet, which is updated with info tricks that might not be covered by the {{hc|articles/360037773573-5th-Edition-OGL-by-Roll20 official sheet documentation}}.<br />
<br />
<br />
To find out about the latest updates, issues and talk about the sheet, check the {{fpl|10096810/ D&D 5th Edition by Roll20 (Q2Y2021)}}-thread on the {{forum|category/277980 forums}}.<br />
<br />
<br />
[[Bug|Bug reports]] for the sheet is best reported in the same thread. If you find bugs in the 5E Compendium or 5E marketplace content, {{bug}}.<br />
<br />
<br />
__TOC__<br />
<br />
==Adding the Character Sheet to a Game==<br />
[[File:D&D5E-Roll20-sheet-selection.png|300px|thumb|right|The Sheet Selection Menu]]An official or community contributed character sheet [[Add_character_sheet#Adding_a_Character_Sheet_to_your_Campaign|can be added to any game when you first create it]]. On the Game Creation screen, underneath the large blue '''“I’m Ready, Create Game!”''' button, is the '''“Optional: Choose a Character Sheet”''' section. Located here is a drop down menu that lists all the character sheets built either by Roll20 officially or created by the community. These sheets are sorted under their respective RPG Systems in alphanumerical order. Once selected, a preview of the character sheet will load upon the creation page for you to review as well as showcase relevant information about the sheet, such as the sheet’s creator and its key features.<br />
<br />
<br />
The '''D&D 5E by Roll20''' Sheet can be found under either: '''Sheets by Roll20''' → D&D 5E by Roll20 OR '''Dungeons and Dragons 5E''' → D&D 5E by Roll20<br />
<br />
<br />
If you want to add a character sheet to an existing campaign, you can find this drop down menu once again by accessing the [[Game Settings Page]] from the [[Game_Management#Game_Details_Page|Game Details]]-page.<br />
<br />
{{mbox | text = '''NOTE:''' If you have added custom attributes to your character journals prior to adding a character sheet to a campaign, you may want to delete them first. Adding a character sheet to a campaign will create its own set of custom attributes on all of your character journals, but it will reuse any attributes encountered if they share the same name. This can cause calculation issues on the sheet.}}<br />
<br />
<br />
If you were previously using either the [[DnD5e Shaped Character Sheet|D&D 5E (Shaped)]] or [[DnD5E_Community_Contributed|D&D 5E (Community Contributed)]] sheets and wish to transfer over to the '''D&D 5E by Roll20''' version, it's a good idea to ask help on the [https://app.roll20.net/forum/category/277980 forums].<br />
<br />
<div style="clear: both"></div><br />
<br />
==Where to Find the Sheet==<br />
Once a character sheet has been added to a game, and once inside it, on all [[Journal#Characters|Characters Journals]], a new tab will be available between the '''“Bio & Info”''' and '''“Attributes & Abilities”''' tab labelled '''“Character Sheet”'''. Much like the Attributes & Abilities tab, only players who have been granted Edit permissions for the journal entry will be able to access the Character Sheet tab.<br />
<br />
''See also:'' '''[[Add_character_sheet#Adding_New_Characters_In-Game|Create new character sheets to your players]]'''<br />
<br />
==Sheet Features==<br />
The '''D&D 5E by Roll20''' sheet has all of the functionality of a pen and paper character sheet, and much more. Certain aspects of the sheet have been streamlined or automated to remove bookkeeping and speed up gameplay. The key features are auto-calculations, [[Macro|macro]] buttons, and [[D&D 5e by Roll20 Roll Templates|roll templates]]. The sheet defaults to using the rules as printed in the D&D 5E SRD, however it's dynamic enough to allow you and your group to use many custom house rules you might want.<br />
<br />
===Auto Calculations===<br />
Many parts of the sheet use auto calculations to fill in derived attributes with the expectation that you're using the rules as printed in the 5th Edition SRD. Many of these calculated traits can be modified from the character sheet's <span style="font-family:Pictos;">y</span> [[D&D 5E by Roll20#Settings Page|Settings]]-tab, and those set by Sheet Workers can be edited directly. Below are some examples of Sheet Worker and Auto Calculation functionality:<br />
<br />
* '''Class''' - Changing the character's class from the header will automatically update the character's saving throw proficiencies, their hit die type, spell casting ability, and spell save DC. <br />
* '''Level''' - Changing the character's level will also update their proficiency bonus, number of spells per day, and more.<br />
* '''Attributes''' - Changing one of the character's attributes will also update the related modifier, skills that are based on that attribute, and derived stats such as initiative or passive perception.<br />
<br />
===Roll Buttons and Roll Templates===<br />
[[File:5E_OGL_Sheet_Rollable_Buttons.gif|right|frame|Any label that highlights in red when the mouse hovers over it is rollable.]]<br />
''Main Page:'' '''[[D&D 5e by Roll20 Roll Templates|D&D 5E by Roll20 Roll templates]]'''<br />
<br />
Most of the stats in the game can be rolled by hovering over their name, the stat will turn red, and then left-clicking the mouse. This is true for Attributes, Saves, Skills, Hit Dice, Death Saves, Tool Proficiencies, Attacks & Spellcasting, Spell Cards, and NPC Actions/Attacks. Any of these roll buttons can be dragged directly from the sheet to your [[Macro Quick Bar]], enabled from the <span style="font-family:Pictos;">y</span> [[My Settings]]-tab of Roll20's [[Sidebar]].<br />
<br />
Player characters have both a simple and attack [[D&D 5e by Roll20 Roll Templates|roll template]] that is output to the {{Text Chat}}-tab on the right hand [[Sidebar]]. The simple template is used for everything except for attacks. The attack template is shaped to show up in three pieces; the attack at the top, information in the middle, and damage at the bottom. Depending on your sheet settings, the damage will not roll automatically unless you click on the name of the attack from the roll template in the chat tab. This was designed to simulate the tabletop experience of rolling to attack and then rolling damage if necessary. You can change this behavior in the sheet <span style="font-family:Pictos;">y</span> [[D&D 5E by Roll20#Settings Page|Settings]]-tab, tab under "Auto Damage Roll".<br />
<br />
<div style="clear: both"></div><br />
<br />
====Rolling for Advantage and Disadvantage====<br />
With the '''D&D 5E by Roll20''' Sheet, the [[D&D 5E by Roll20#Settings Page|default sheet settings]] has Advantage set to ''always'' rolled for convenience purposes. It is commonly agreed upon that a gaming group uses the left roll result when advantage is not being used for a check. When advantage or disadvantage is in play, simply choose the higher or lower result among the two per usual. You can change this behavior in the sheet <span style="font-family:Pictos;">y</span> [[D&D 5E by Roll20#Settings Page|Settings]]-tab (gear icon at the top right of the page), tab under "Roll Queries". You have the choice of "Always Roll Advantage" (the default setting), "Advantage Toggle", "Query Advantage", or "Never Roll Advantage".<br />
<br />
'''Advantage Toggle:''' The Advantage Toggle will add three buttons to the top of your character sheet: "Advantage", "Normal", and "Disadvantage". You can click on any of these to roll for Advantage (the highest roll result will highlight in black), Disadvantage (the lowest roll result will highlight in black), or a single d20.<br />
<br />
'''Query Advantage:''' The Query Advantage setting will prompt a dialog box to appear whenever you roll from your sheet. It will ask you to select what sort of roll want to do (Normal, Advantage, Disadvantage). After choosing the type you want, the roll will occur in chat.<br />
<br />
'''Never Roll Advantage:''' When rolling from your sheet, only a single d20 will be rolled.<br />
<br />
===Resizable Text Fields===<br />
[[File:5E_OGL_Sheet_Resizable_Text_Fields.gif|right|frame|Making a text field larger is just a matter of click and dragging.]]There are many free-text fields on the sheet that give you a place to keep information that doesn't necessarily follow a specific format. All of the fields on the Bio Tab are free-text fields as well as the Description fields present for attacks, spells, equipment, features & traits, and NPC actions. If your text overflows past the bottom of a text field, you can resize it to view the content in its entirety by clicking and dragging the bottom right corner icon shown in the adjoining image.<br />
<br />
<br />
At present, these fields can only contain raw text. There are no formatting options (bold, italic, etc.) available.<br />
<br />
<div style="clear: both"></div><br />
<br />
===The Padlock Button and Organizing Elements===<br />
(aka. '''[[Character_Sheets#Repeating_Section|Repeating Section]]''')<br />
[[File:5E_OGL_Sheet_Padlock.gif|right|frame|The Padlock Toggle]]There is a <span style="font-family:Pictos;">(</span> (padlock) icon set at the bottom of several different fields of the '''D&D 5E by Roll20''' Sheet. It is used where a player is meant to add entries such as individual attacks, actions, pieces of equipment, features & traits, tool proficiences & custom skills, other proficiencies & languages, and spells. This icon behaves as a toggle button. <br />
<br />
When set in the <span style="font-family:Pictos;">(</span> locked position (default), a player can add new entries into the field. When the button is toggled to <span style="font-family:Pictos;">)</span>(unlocked), a player can no longer add new entries, but they will be able to reorder or delete any of the existing ones. The <span style="font-family:Pictos;">#</span>(red trash bin)-icon overlaid on the right hand side of the entry will delete it.<br />
<br />
{{Ambox<br />
|nocat=true<br />
| type = content<br />
| text = '''Deleting an entry cannot be undone!''' On left side of every entry while the padlock is <span style="font-family:Pictos;">)</span> unlocked is a re-sort icon symbolized by '''<big>≡</big>'''(three parallel lines). By clicking and dragging on this icon, you can rearrange the order of the entries in the field.<br />
}}<br />
<br />
{{Ambox<br />
|nocat=true<br />
| type = content<br />
| text = Some of the features of '''Repeating Sections''' do not work when the [[Character_Sheets#Character_Sheet_in_a_separate_window|Character Sheet is in a separate window]].<br />
}}<br />
<br />
<br />
<div style="clear: both"></div><br />
<br />
==Utilizing the 5th Edition SRD Compendium==<br />
[[File:5E_OGL_Sheet_Compendium.png|right|The Compendium Tab]]Upon adding the D&D 5E by Roll20 Character Sheet to a campaign, the [https://app.roll20.net/compendium/dnd5e/BookIndex| 5th Edition SRD Compendium] is automatically enabled for use from it's own <span style="font-family:Pictos;">i</span> [[Compendium]]-tab in the '''[[Sidebar]]''' of the application. It's located between the {{Journal}} and <span style="font-family:Pictos Custom;">u</span> [[Jukebox]]-tabs, and is accessible for both GM and Player alike.<br />
<br />
<br />
The <span style="font-family:Pictos;">i</span> [[Compendium]] allows for rapid searching of all rules, classes, monsters, spells, items, and more that are included in the 5th Edition SRD. This minimizes time spent for the gaming group to leaf through a book in the middle of a session for a rule clarification. Even better, both the GM and the Player can utilize dragging and dropping* from the <span style="font-family:Pictos;">i</span> [[Compendium]]-tab directly to your character sheets. This makes statting NPCs and PCs far faster than inputing everything manually.<br />
<br />
{{mbox | text = '''NOTE:''' The 5th Edition SRD is similar but NOT identical to the ''Dungeons and Dragons'' 5th Edition Rule Book. Some skills, classes, creatures, items, and other elements found within the ''Dungeons and Dragons'' rule book are strictly intellectual property of Wizards of the Coast and not accessible through their Open-Game License(OGL).}}<br />
<br />
<br />
===Statting PCs===<br />
Dragging from the <span style="font-family:Pictos;">i</span> [[Compendium]] works for the Equipment and Spell fields of the PC Sheet. This will not only carry over the name of the item or spell, but the relevant attack and damage rolls and any rules or flavor text that comes with it. Adding Compendium items in this fashion also automatically adds the equipment item (if it's a weapon) or spell to the Attacks & Spellcasting field to roll directly from. Items that modify a character's Attributes, Saves, AC, To Hit, Damage, Spell Attacks, and Spell DC will be automatically calculated on the sheet when dragged in. For example, if a Belt of Giant Strength is dragged to a sheet, the strength Attribute Score will become highlighted in blue and its attribute score will be increased. An asterisk is appended to the right of the score to also signify that it has been modified by an item. When you mouse over this number, the strength Attribute Score will revert back to what its unmodified total so you can refer back to it. Dropping a Compendium items that is an ammunition type (arrows, crossbow bolts, blowgun darts, etc) will automatically fill out a resource field for that item and link it to its entry in the Equipment section.<br />
<br />
To insert a Compendium item into the character sheet, run a search for the Item or Spell you want to add in the <span style="font-family:Pictos;">i</span> [[Compendium]]-tab. Once found, click and drag on the Compendium item's name so that it creates a little named tile that follows along with your mouse. Drag this over to the character sheet, it doesn't matter where. A text box that reads, "ACCEPTING DROP FROM COMPENDIUM" will appear on your sheet if this is done correctly. Let go of the tile and the entry will be auto-completed with all the data pertaining to the the Compendium entry in the correct location on the sheet. You can see this in action below under [[#Equipment|Equipment]].<br />
<br />
===Statting NPCs===<br />
You can fill out an entire NPC sheet in a single drag and drop. Run a search for the NPC you want to create from the <span style="font-family:Pictos;">i</span> [[Compendium]]-tab. Once found, click and drag on the NPC name so that it creates a little named tile that follows along with your mouse. Drag this to anywhere over the Tabletop area of the screen. Let go of the tile and a new character journal will be created named after the NPC from the Compendium entry. Its sheet will be changed over to the NPC sheet and filled with the entire NPC entry from the Compendium including their Actions, Reactions, and Legendary Actions if applicable. If you're using one of the Compendium expansions bought from the Roll20 Marketplace like the Monster Manual or Volo's Guide to Monsters, token art will also be pulled from the Compendium entry, placed on the table, and linked to your NPC's journal.<br />
<br />
You can also drag an NPC entry from the Compendium to an existing journal entry if you have the sheet open. If the sheet is in PC sheet mode, it will automatically change it over to the NPC sheet, and add its entry elements to it.<br />
<br />
One thing to note about dragging a stat block over from the Compendium is that it uses an ''additive'' behavior. It will not replace anything that you have already entered manually.<br />
<br />
=The PC Sheet=<br />
The '''D&D 5E by Roll20 Sheet''' contains both the PC Sheet ''and'' the NPC Sheet. By default, a new character journal is set to the PC sheet, but you can switch between the two by toggling it from the [[#Settings Page|General Options Settings]]. The PC Sheet is split up into four pages and can be selected from the buttons just underneath the header at the top of the sheet. They are listed from left to right order: The [[#Core Page|Core Page]], The [[#Bio Page|Bio Page]], The [[#Spells Page|Spells Page]], and The [[#Setting Page|Setting Page]].<br />
<br />
== Creating and Leveling up a character with Charactermancer ==<br />
Players and GMs using the '''D&D 5E by Roll20''' Sheet can use the Charactermancer to create and level up characters.<br />
<br />
'''How to use the Charactermancer for [[Charactermancer (D&D Fifth Edition)|character creation and leveling]].'''<br />
<br />
<br />
{{Ambox<br />
|nocat=true<br />
| type = content<br />
| text = The Charactermancer do not work when the [[Character_Sheets#Character_Sheet_in_a_separate_window|Character Sheet is in a separate window]].<br />
}}<br />
<br />
==Core Page==<br />
[[File:5E_OGL_PC_Core_Guide.jpg|right|frame|The Core Page]]The Core Page is selected by default and has most of the information you'll want to use on a regular basis to play your character. This should look very similar to the content you would normally find on the first sheet of the physical "D&D 5E by Roll20" player character sheet. The screenshot at the top of this wiki page displays the entirety of the Core Page. <br />
===(1) Core Header===<br />
[[File:D&D5E-Roll20-core-header.png|550px]]<br />
<br />
The header block at the top of the sheet changes based on the page you have selected. On the Core page you can select a class by its dropdown menu. The available options from the dropdown are: Barbarian, Bard, Cleric, Druid, Fighter, Monk, Paladin, Ranger, Rogue, Sorcerer, Warlock, and Wizard. You can create a custom class from the Settings Page.<br />
<br />
Once a class has been selected you can update the class's level by changing the number next to the class. The sheet will also automatically mark the abilities that class has proficiency in as well as automatically select the dice that will be used when Hit Dice are rolled. You can change the Hit Dice setting manually from the options menu. If your character multi-classes, then the secondary class and its level will appear beside the primary class. This Class and Level field can hold up to four classes if desired.<br />
<br />
The fields for Background, Race, Alignment, and Experience Points allow you to fill in whatever text you wish to put in them. The Character Name persists over all pages of the sheet and is tied to the name you give to the journal entry. Changing it on the sheet itself will also change the name on the character journal and vice versa once it is closed.<br />
<br />
===(2) Attributes===<br />
<br />
[[File:5E_OGL_Sheet_Attribute_Block.jpg|left]]Along the left side of the sheet are listed the 6 primary attributes: Strength, Dexterity, Constitution, Intelligence, Wisdom, and Charisma. These attributes are used by almost every other calculation on the sheet, as they are the core definition of a character. Each attribute block has the core attribute score, which can be changed by modifying the number in the oval at the bottom of each block, and, inside the square, the attribute modifier which is auto-calculated based on the score below it. All racial ability score increases must be manually added to the core attribute score using the settings "gear" symbol at the top of the page (where the Core, Bio, and Spells buttons are located.) The attribute modifier uses the following calculation to set the value:<br />
<br />
<br />
<code>[[floor((@{strength}-10)/2)]]</code><br />
<br />
The attribute can be referenced by its name, such as @{dexterity} while the attributes modifier can be referenced by adding the mod suffix, @{dexterity_mod}.<br />
<br />
<div style="clear: both"></div><br />
<br />
===(3) Inspiration===<br />
<br />
[[File:D&D5E-Roll20-inspiration.png|left]]You can track whether or not you have Inspiration by clicking the circle next to the Inspiration block at the top left of the Core page. This will toggle a dragon spiral icon on and off for indication purposes.<br />
<br />
<div style="clear: both"></div><br />
<br />
===(4) Proficiency Bonus===<br />
<br />
[[File:5E_OGL_Sheet_Proficiency.png|left]]Your character's proficiency bonus is listed near the top left of the page. You cannot modify this value manually, instead it is automatically set based off your character's over-all level. Your character's Level can be set by changing the number next to your Class name in the [[#header_info|Header]] at the top when on the Core page.<br />
<br />
<div style="clear: both"></div><br />
<br />
===(5) Saving Throws===<br />
<br />
[[File:5E_OGL_Sheet_Saving_Throws.png|left]]Next to the core Attributes on the left side of the page is a list of the same attributes to be used in making saving throws. To mark an attribute that your character has proficiency in for saving throws, check the box next to the appropriate attributes. When you select a class in the header section of the Core page it will automatically check the correct boxes for that class's proficiencies.<br />
<br />
You can add an additional field to Saving Throws to serve as a Global Save Modifier. An example is if the character is under the influence of the Bless spell and can roll a 1d4 in addition to the result of their saving throws. This is enabled from the Settings Page under General Options. Once enabled a seventh checkbox and field will be added at the bottom of the Saving Throws block with a text field to enter the additional die roll. For this example, you could enter "1d4[BLESS]" in the global checkbox's text field that you can enable when the character is under the effects of the Bless spell. The word between the brackets becomes a label that can be seen when you mouse over the roll result in chat. While this Global Save Modifier is checked, every roll made from the Saving Throws block and performing a Death Save will add this modifier to the result.<br />
<br />
<div style="clear: both"></div><br />
<br />
===(6) Skills===<br />
[[File:5E_OGL_Sheet_Skills.png|left]]<br />
To the right of the Core Attributes is a list of all of the character's Skills. Each skill can be rolled by clicking on the skill name. If you have proficiency in a specific skill, then you would check the box next to the skill name, this will automatically add your proficiency bonus to that skill's checks. Each skill also lists the core attribute, that is used in the roll calculations, next to it in parenthesis.<br />
<br />
You can set advanced skill options for the Settings page, such as skill expertise, flat bonuses from class archetypes or feats, as well as Jack of All Trades.<br />
<br />
<div style="clear: both"></div><br />
<br />
===(7) Armor Class, Initiative, & Speed===<br />
<br />
[[File:D&D5E-Roll20-AC-Init-Speed.png|left]]The Armor Class & Speed blocks at the top center of the page can be used to keep track of your Armor and Speed values. The Initiative block cannot be modified manually, but instead is auto-calculated based off your character's Dexterity. If you have any additional initiative modifiers you can add them on the {{gear}} [[#Settings Page|Settings Page]] under Initiative Modifier in the Class Options block.<br />
<br />
Armor Class can also be tracked automatically by using the [https://app.roll20.net/compendium/dnd5e/BookIndex Compendium] compatible inventory, on by default.<br />
<br />
You can configure a custom AC calculation using the {{gear}} [[#Settings Page|Settings Page]] under the Attribute Tracking section. It's listed as "Armor Class Tracking" and is set to "Automatic" by default. If you select Custom, you can select up to two different attributes to apply to the character's armor class.<br />
<div style="clear: both"></div><br />
<br />
====Using the Global AC Modifiers====<br />
If you check the "Show Global AC Modifier" field in the character sheet General Options settings, the sheet will display a repeating section to configure and apply different modifiers to AC. So, for example, if your character has a common bonus, such as from a spell or a conditional feat or fighting style, you can toggle that AC bonus from the character sheet directly.<br />
<br />
====Rolling for Initiative and the Turn Order Tracker====<br />
Clicking on the word INITIATIVE will roll that character's initiative score. If your players have [[Token|tokens]] linked to their character sheets, they can roll their initiative ''and'' simultaneously add their character and its initiative score to the {{Turn Tracker}} automatically. What is required of the player is that their linked token must be currently selected on the Tabletop before they roll off their sheet.<br />
<br />
If you would like to enable a tie breaker component to Initiative, there is an option to enable this from the [[#Settings Page|Settings Page]] under the "Attribute Options" block. What this does is that it will add your dexterity Attribute Score as a decimal value to your Initiative. So if you have a character with a dexterity attribute score of 14, your initiative modifier will change from a <code>2</code> to a <code>2.14</code>.<br />
<br />
===(8) Hit Points & Temporary Hit Points===<br />
[[File:5E_OGL_Sheet_HP.png|left]]The Current Hit Points and Temporary Hit Points blocks are used to keep track of your character's Hit Points (HP). Inside the Current Hit Points block, at the top, is a line that lists the character's maximum amount of HP. <br />
<br />
<br />
When your character takes damage, if they have any, it should be subtracted from their Temporary Hit Points first, then any remaining damage would then come off of the character's Current Hit Points.<br />
<br />
<div style="clear: both"></div><br />
<br />
===(9) Hit Dice===<br />
[[File:5E_OGL_Sheet_Hit_Dice2.png|left]] The Hit Dice block is used to keep track of and roll your character's hit dice. Inside the Hit Dice block, at the top, is a line to keep track of the total number of dice your character can have. In the main area of the block you would keep track of the remaining hit dice. Clicking the "HIT DICE" label will roll the hit dice for your selected class automatically. If you wish to change the dice that is rolled you can do so in the Class Options section of the [[#Settings Page|Settings Page]] ({{gear}} icon). <br />
<br />
<br />
If your character is multi-classed, when rolling your hit dice (by clicking "''HIT DICE''", a pop-up will ask which of your character's current class's hit dice you want to roll. This input accepts only numerals a input to make automatic tracking of the [[API:A Guide to the API|API]] possible.<br />
<div style="clear: both"></div><br />
<br />
===(10) Death Saves===<br />
[[File:5E_OGL_Sheet_Death_Saves.png|left]]The Death Saves block is used to keep track of your character's death save rolls once they have been knocked out. You can click the "DEATH SAVES" label to make a death save roll. If you roll greater than 10 you would check one of the boxes next to "Successes" otherwise you would check a box next to "Failures". If your character has any modifiers to their death save rolls they can be added in the Class Options section of the Settings Page(gear icon).<br />
<div style="clear: both"></div><br />
<br />
===(11) Attacks & Spellcasting===<br />
[[File:5E_OGL_Sheet_Attacks_And_Spellcasting.png|left]]The Attacks & Spellcasting block in the center of the Core page of this character sheet will be one of the most often used sections. To start, you can manually add any attack or spell to this section by hovering over the block and clicking the "Add" button(the <span style="font-family:Pictos;">&</span> symbol). This will open a form that can be filled out with all of the information about the specific attack or spell you are adding. <br />
<br />
<br />
This section will automatically add attacks, with all the stats, for spells that have an attack component when they are added to your spell sheet on the [[#Spells Page|Spells Page]]. This happen both if you add the spell manually or if you drag and drop a spell from the <span style="font-family:Pictos;">i</span> [[Compendium]]. An attack is also automatically created if you drag and drop an item from the Compendium into your sheet.<br />
<br />
<div style="clear: both"></div><br />
[[File:Poisoned Dagger 5e Attack.png|right|frame|An example of an attack form filled out for a physical attack using a +1 Poisoned Dagger]]For example, lets say Erin the Bold has a +1 Poisoned Dagger that has the stats of a regular dagger, but also metes out an additional 1d6 of poison damage alongside the typical 1d4 points of piercing damage. The image displayed to the right is how the attack would be set up:<br />
<br />
<br />
Since this is a [https://app.roll20.net/compendium/dnd5e/Items:Dagger#h-Dagger dagger], and daggers have the "[https://app.roll20.net/compendium/dnd5e/Weapons#h-Weapons Finesse]" attribute I can chose either STR or DEX for my bonus attribute. Erin is quicker than she is strong, so we will pick DEX as the attribute to attack with, as well as checking the "proficient" checkbox since Erin is experienced with using these sorts of weapons. She doesn't have any other gear that might make her attacks better, so we will leave the generic bonus between the attribute and proficiency blank, or 0. Being a +1 Poisoned Dagger means that it is also magical, so it gets a 1 in the magic bonus slot just below. A dagger can also be used as a thrown weapon, so we've added the weapon's throwing range info to the "Range" field. Since a weapon does damage, we have checked the first "Damage" checkbox and filled in the required fields. This dagger does 1d4 piercing damage + Erin's DEX mod + 0 bonus damage (this would be used for bonus damage on top of the magical +1) and it doesn't have anything to change the critical damage so we just put the same damage into the "crit" box. Because this dagger can also cause poison damage, we also check the second "Damage" checkbox and fill in the info for the 2nd set of damage. The poison does a flat 1d6 poison with no extra bonuses, so we've selected "-" to say there is no attribute that adds to this damage. This damage also doesn't have anything to make the crit different so we set that to 1d6 as well. There are no extra saving throws or effects that are included with this attack, so we leave these additional sections blank. <br />
<br />
These additional effect sections will be used more commonly with spells, like [https://app.roll20.net/compendium/dnd5e/Fireball#h-Fireball Fireball], where you would require a DEX save against your SPELL DC, which will be set according to your character's spell casting level. For a fireball, the save effect would be "half damage" and the "Description" would be something like "Hits all creatures within 20 ft of the explosion point".<br />
<br />
After you are done modifying all of individual stats for an attack you can click the gear icon at the top right of that section and it will hide the stats for that attack. If ever you need to change these stats in the future you can hover over the entry and click the <span style="font-family:Pictos;">y</span>(gear)-icon that shows up to unhide the stats section. <br />
<br />
<div style="clear: both"></div><br />
====Adding Global Attack and Damage Modifier====<br />
You can add two special entries to the Attacks & Spellcasting block to handle to global Attacks and Damage modifications to rolls. An example is if the character is under the influence of the Bless spell and can roll a 1d4 in addition to the result of their attack roll. This is enabled from the [[#Settings Page|Settings Page]] under General Options. Once enabled, a checkbox will be added at the bottom of the Attacks & Spellcasting block with a text field to enter the additional die roll. For this example, you could enter <nowiki>"1d4[BLESS]"</nowiki> in the global checkbox's text field that you can enable when the character is under the effects of the Bless spell. The word between the brackets becomes a label that can be seen when you mouse over the roll result in chat. While these Global Modifiers are checked, every roll made from the Attacks & Spellcasting block will add these modifiers to the result.<br />
<br />
====Rolling from the Attacks & Spellcasting Block====<br />
[[File:Poisoned Dagger 5e Roll.png|frame|An attack roll from a +1 Poisoned Dagger]]Rolling from the Attacks & Spellcasting Block is no different than rolling from any other portions of the character sheet. Hovering your mouse over any entry here will highlight its entire label (NAME, ATK, and DAMAGE/TYPE) in red and you'll be able to click on it to roll the attack or spell. You can also drag this entry into the Macro Bar to give yourself easy access to this attack. Because this is a repeating section, the macro name will be a bit messy, but you can right-click the button and rename the macro to whatever you like.<br />
<br />
With any attack that checks for AC, you will see TWO rolls set side by side for the Armor Class check with the name of the attack listed underneath them with the Attack modifier bonus (ATK) appended to the Attack name in light grey. The Roll20 D&D 5E Character Sheet ''always'' rolls for Advantage by default, so you will always have two roll results for this check (most gaming groups use the left roll result if neither Advantage or Disadvantage is being factored in the check). If there is a specified range for the attack, this will be listed above the attack's name.<br />
<br />
Underneath the AC Check and Attack Name is the Damage roll result for the attack. Underneath this roll result will be the Damage Type (ex. slashing, piercing, poison, fire, etc.) listed in light grey italicized font.<br />
<br />
For spells that don't check for AC and instead require a Saving Throws to mitigate or negate the spell's effect, the SPELL DC is listed first. Underneath this, in italicized font, is the effect if a character succeeds the check listed. Underneath the effect is the required attribute saving throw that must be rolled. If Damage is applied, this result is rolled and listed next with its Damage Type.<br />
<br />
[[File:5e_attack_example.gif|right|frame|How to view attack damage when the sheet is set to "Don't Auto Roll Damage"]]<br /><br />
<br />
<br />
{{mbox | text = '''NOTE:''' If your character sheet's Settings have "Auto Damage Roll" set to "Don't Auto Roll Damage" under General Options, the damage will not be listed underneath the AC roll result in chat. The damage was rolled, but presently hidden from view. Anyone can see the damage delivered by manually unfolding the roll result open by hovering your mouse over the roll result in chat and clicking on the attack/spell's name.}}<br />
<div style="clear: both"></div><br />
<br />
===(12) Personality Traits, Ideals, Bonds, and Flaws===<br />
These text fields lock to prevent accidental edits. When a sheet is first created, these fields are unlocked and given a dashed yellow border to the top of the field to showcase that they're editable. To lock the field after entering text, click on the gear icon in the upper right corner of the field. This will remove the yellow border and the field will conform in height to display everything within it.<br />
<br />
There presently isn't a means to format the raw text (italicize, bold, font alignment, etc) within these fields and any line breaks are stripped out. If you ever need to edit the content again while the field is locked, mouse over the desired field and the gear icon will reappear in the top right. Clicking on that will unlock the field once again for edits.<br />
<br />
===(13) Class & Other Resources===<br />
[[File:5E_OGL_Sheet_Resources.png]]<br />
<br />
The Class & Other Resource Blocks can be used to keep track of either an item quantity you have in your equipment (like arrows in a quiver), or skills that don't fit into the other sections on the sheet (like a '''Sorcerer's Sorcery Points''', a '''Cleric's Channel Divinity''' at higher levels, or the number of rounds a '''Barbarian''' has been '''Raging''' so far in a combat encounter).<br />
<br />
There are 3 fields per Block:<br />
* Resource Max:<br />
** The Resource Max field is a text box which allows you to quantify exactly what you're tracking (ex. "Total: 10 Rounds").<br />
* Resource:<br />
** The Resource field is a numeral that you dial up or down or input directly.<br />
* Resource Name:<br />
** The Resource Name is a text box that allows you to label the resource when you click on the light grey "OTHER RESOURCE" label to overwrite it with your own.<br />
**"OTHER RESOURCE" is placeholder text<br />
<br />
<br />
A resource block will be filled automatically if you checkmark an Equipment item as "USE AS A RESOURCE" & the Item Quantity field will be paired with the Resource field in the Resource block & vice versa (you'll need to click outside of the field or hit Enter for changes to refresh across the sheet). If the two resource blocks given by default are not enough then you can add additional blocks by hovering over the section & clicking the "Add" (+ symbol) button.<br />
<br />
The Item Name will also be added to the Resource Name field, however the Resource Max field is apparently not linked to the Item currently.<br />
<br />
If you drag & drop an ammunition item type from the Compendium into your character sheet, the item is added to the Equipment block & is automatically listed & linked as an Other Resource.<br />
<div style="clear: both"></div><br />
To call the first set of class resources use:<br />
* Class Resource <code>@{class_resource}</code><br />
* Other Resource <code>@{other_resource}</code><br />
<br />
<br />
To call the Repeating resources use<br />
* Repeating Resource 1st left<code>@{repeating_resource_$0_resource_left}</code><br />
* Repeating Resource 1st right<code>@{repeating_resource_$0_resource_right}</code><br />
* Repeating Resource 2nd left<code>@{repeating_resource_$1_resource_left}</code><br />
* Repeating Resource 2nd right<code>@{repeating_resource_$1_resource_right}</code><br />
* etc.<br />
<br />
<br />
If you want to do a basic Full Readout of the Repeating Resource, the Format would be (Top Left to Bottom Right):<br />
* Class: <code>@{class_resource_name}: @{class_resource} / @{class_resource|max}</code><br />
* Other: <code>@{other_resource_name}: @{other_resource} / @{other_resource|max}</code><br />
* Left 0: <code>@{repeating_resource_$0_resource_left_name}: @{repeating_resource_$0_resource_left} / @{repeating_resource_$0_resource_left|max}</code><br />
* Right 0: <code>@{repeating_resource_$0_resource_right_name}: @{repeating_resource_$0_resource_right} / @{repeating_resource_$0_resource_right|max}</code><br />
* Left 1: <code>@{repeating_resource_$1_resource_left_name}: @{repeating_resource_$1_resource_left} / @{repeating_resource_$1_resource_left|max}</code><br />
* Right 1: <code>@{repeating_resource_$1_resource_right_name}: @{repeating_resource_$1_resource_right} / @{repeating_resource_$1_resource_right|max}</code><br />
* etc.<br />
<br />
===(14) Tool Proficiencies===<br />
[[File:5E_OGL_Sheet_Tool_Proficiencies.png|left]]The Tool Proficiencies block is for listing a character's Tool Proficiency skills. At the bottom of this block is an "Add" (<span style="font-family:Pictos;">&</span> symbol) button. Clicking this will add a new entry to this block where you can add all of the relative stats for a specific tool proficiency, say Woodcarver's Tools. You can set the level of proficiency to either Proficient, Expertise, or Jack of All Trades. The roll bonus for that tool will reflect the proficiency level selected. Next is an Attribute drop down menu where you can select which character attribute to roll with for a proficiency check. One of the options you can choose is "QUERY ATTRIBUTE" which when you click on the Tool Proficiency to roll it, you will be prompted to choose which attribute you would like to use. The attribute used for the check will be up to the GM when it is time to make the roll check. If there is any additional bonus modifiers that come along with the tool in question, you can input it in the "MODS:" field.<br />
<br />
Once you finished filling out the stats for this tool you can click the <span style="font-family:Pictos;">y</span>(gear) icon at the top right of the entry to hide the stat fields and leaving behind just the rollable button. You can roll by either clicking on this rollable button or dragging it to your [[Macro Bar]].<br />
<br />
You can also use this section to create custom skills or rolls for your campaign setting or home-brew ruleset. Check out the [[#Custom Skills and Stats|Advanced Use]] section for further details.<br />
<br />
====Global Skill Modifier====<br />
You can add a special entry to the Tool Proficiencies & Custom Skills block to handle to global Attacks and Damage modifications to rolls. An example is if the character is under the influence of the Guidance spell and can roll a 1d4 in addition to the result of their skill check. This feature is enabled from the [[#Settings Page|Settings Page]] under General Options. Once enabled, a checkbox will be added at the bottom of the Tool Proficiences & Custom Skills block with a text field to enter the additional die roll.<br />
<br />
For this example, you could enter "1d4[Guidance]" in the global checkbox's text field that you can enable when the character is under the effects of the Guidance spell. The word between the brackets becomes a label that can be seen when you mouse over the roll result in chat. While this Global Modifier is checked, every roll made from the Tool Proficiencies & Custom Skills block and the Skills block will add this modifier to the result.<br />
<div style="clear: both"></div><br />
<br />
===(15) Other Proficiencies & Languages===<br />
[[File:5E OGL Sheet Proficiencies.png|left]]<br />
This block can be set up to be Compendium Compatible (where you can add repeating sections for individual items) or as one resizable free-text field to enter whatever you wish in here. If you don't feel the Tool Proficiency block is needed (as in, you don't feel like your party will ever have to roll individual tool sets), you can store a character's Tool Proficiencies here instead. There presently isn't a means to format the raw text (italicize, bold, font alignment, etc). You can adjust this block's behavior by going to the Settings Page of the sheet and going to the General Options block to change whether this block uses the Simple or Compendium Compatible layout.<br />
<br />
When the Other Proficiences & Languages block is made Compendium Compatible, each repeating field lists a Type selection field and a Proficiency text field. Type has the following options available from its drop down selection menu: Language, Weapon, Armor, Other. <br />
<p style="clear:both;"></p><br />
<br />
===(16) Equipment===<br />
[[File:5E OGL Sheet Equipment.png|framed|right|The Equipment block of the PC Sheet]]<br />
The Equipment block at the bottom of the page has 2 different versions: a Simple version that features a single plain text field where you can track all of your equipment in any format you wish and a Compendium Compatible version that allows you to drag and drop items from the Compendium to automatically populate repeated sections for each indivdual piece of equipment.<br />
<br />
To swap between the two different Equipment block versions, first, go to the sheet's Settings Page (gear icon at the top right of the page) and then to the "General Options" section. Here, on the field labeled "Inventory", you can select between "Simple" or "Compendium Compatible" respectively. Like the name implies, if you want to be able to copy items directly from the Compendium using drag and drop, you must use the Compendium Compatible version. Dragging item entries from the Compendium to the character sheet will add it fully filled in the Equipment section as well as other automated actions described below.<br />
<br />
====Automated Compendium Functionality====<br />
If you populate the Equipment block by dragging and dropping <span style="font-family:Pictos;">i</span> [[Compendium]] items, there are several automatic features that occur when the entries you drag in our equipment items.<br />
Auto-Equip: Every item dragged to the sheet is automatically equipped in the Equipment Section<br />
*'''Weapons:''' A weapon dragged in from the Compendium will add an attack in the Attacks and Spellcasting section for that item.<br />
*'''Armor:''' Armor that is dragged in from the Compendium will add its bonus to the Armor Class (while equipped) section. If you drag multiple pieces of armor to the same sheet and at least two armor entries are equipped at once, a warning will pop up in red at the top of the Equipment Block that the Armor Class isn't being correctly calculated because of the bonus overlap. This warning will dissapear when you unequip down to a single set of armor.<br />
*'''Magical/Wondrous Items:''' Items that modify Attributes, Saves, AC, To Hit, Damage, Spell Attacks, and Spell DC will add that bonus to those elements on the sheet. In most cases, the attribute that is being modified will highlight in blue and followed with an asterisk to showcase that the attribute is being modified by an item. Mousing over the modified number will display the base value of that attribute before the item's modification is applied. This stat modification only applies if the item is equipped in the Equipment section and it will remove its bonus if it is unequipped.<br />
*'''Ammunition:''' Items dragged in from the Compendium that are used for ammunition such as arrows, bolts, darts, and slingstones, will automatically populate and link to an Other Resource field.<br />
<br />
====Manually Adding Items====<br />
You can also add items manually by hovering over the block and clicking the "Add" button (+ symbol). Each equipment entry, by default, show fields for quantity, name, and weight of an item. If you hover over a row and click the small "information" icon (grey-filled circle with a lowercase i centered in it) that appears at the bottom right of the entry you can also set some additional features. <br />
<br />
*'''Equipped Checkbox:''' The checkbox changes the appearance of the Item Name so it's easier to tell what your character currently has equipped from a glance. When left unchecked, the Item Name's font turns grey. When checked, the Item Name becomes a solid black.<br />
*Use As A Resource Checkbox: When checked, this will enable one of the Class Resource blocks and list the item name and its quantity within it. The quantity is tied between the two so changing it in one will be reflected in the other field after clicking outside the field.<br />
*'''PROP:''' This is a text field where you would take note of weapon properties such as ''finesse'', ''versatile'', or ''light''.<br />
*'''MODS:''' This is a text field where you would take note if an item (likely magical) would modify your stats in some fashion such as a character's Attributes, Saves, Skills, AC, To Hit, Damage, Spell Attacks, and Spell DC. If a stat is modified here, its attribute value will become highlighted in blue and adjusted by the supplied modifier listed here. An asterisk is appended to the right of the value to also signify that it has been modified by an item. While your mouse is hovering over the attribute, it will revert back to its unmodified total so you can refer back to its pre-moddified value.<br />
**The format for a stat modification is ''stat name:n'' where n is the stat bonus (ex. ''Strength:21'')<br />
*'''Description Field:''' This is a simple text field to include a description of the particular item and of any special qualities or effects it might have on the player.<br />
Some if not all of these fields will be filled in automatically when adding from the Compendium (where applicable).<br />
<br />
Both versions of the equipment field have the sections for each of the [https://app.roll20.net/compendium/dnd5e/Treasure#h-Treasure coins] you may find on your adventures: copper(CP), silver(SP), electrum(EP), gold(GP), and platinum(PP).<br />
<br />
====Encumbrance====<br />
If you are following Encumbrance rules, the <span style="font-family:Pictos;">i</span> [[Compendium|Compendium Compatible]] Equipment block will automatically calculate and track the weight of your character's backpack if you enter the weight values for any of the items in your Equipment list. When your character becomes encumbered, and depending on its severity, the words ENCUMBERED, HEAVILY ENCUMBERED, or IMMOBILE will display in red underneath the TOTAL WEIGHT value. You can also choose to follow Simple, Variant Encumbrance rules, or not follow Encumbrance rules at all by toggling it off on the [[D&D 5E by Roll20#Settings Page|Settings Page]] under "General Options".<br />
<br />
====Mods====<br />
The Mods field of each piece of equipment can modify the values of ability scores, AC, saving throws, Skill (Ability) checks and more. What follows is a list of the modifiers, and the proper syntax for adding them.<br />
<br />
All modifiers are separated by commas. There are other modifiers that can appear the mod field, used in creating the item from a compendium drag and drop operation, but the modifiers below have live effects on the character sheet, depending on if the item is marked as “equipped”.<br />
<br />
'''replace the <code>+n</code>, with the number you want.''' For example, if you want to boost Animal Handling skill by 3, you look at the table and find <code>Animal Handling +n</code>, so you will add to your item <code>Animal Handling +3</code>.<br />
<br />
{| class="wikitable" <br />
|-<br />
! Modifier<br /><br />
! Effect<br /><br />
|-<br />
| style="width: 20%;" | '''Combat Modifiers'''<br />
| '''These affect items that provide attacks (Appear in the attack section of the character sheet)'''<br />
|-<br />
| Melee Attacks +n<br />
| Adds +n hit "Magic Bonus" to that attack. It is not global, and only affects a weapon(melee or ranged), not an item, staff or other category. The bonus is figured into the attacks display on the 5e sheet.<br />It is NOT ''Melee Attack''.<br />
|-<br />
| Melee Damage +n<br />
| Adds +n damage "Magic Bonus" to that attack. It is not global, and only affects a weapon(melee or ranged), not an item, staff or other category. The bonus is listed separately in the attacks display on the 5e sheet.<br />
|-<br />
| Spell Attack +n<br />
| Adds a global +n to the character's Spell Attack bonus.<br />It is NOT ''Spell Attacks.''<br />
|-<br />
| '''Saving Throws'''<br />
| '''All modifiers stack with “Saving Throws +n'''<br />
|-<br />
| Strength Save +n,<br />Dexterity Save +n,<br />Constitution Save +n,<br />Intelligence Save +n,<br />Wisdom Save +n,<br />Charisma Save +n<br />
| Adds a +n to the indicated saving throw<br />''Do not use a colon.''<br />
|-<br />
| Saving Throws +n<br />
| Adds a Global Modifier to ALL saving throws.<br />
|-<br />
| Spell DC +n<br />
| Adds a global +n to a spell casting character’s Spell Save DC.<br />It is NOT Spell ''Save'' DC.<br />
|-<br />
| '''Ability Scores'''<br />
| <br />
|-<br />
| Strength +n,<br />Dexterity +n,<br />Constitution +n,<br />Intelligence +n,<br />Wisdom +n,<br />Charisma +n<br />
| Provides a bonus to the indicated ability score, which will appear in blue on the sheet while the bonus is active.<br />Do not use a colon. ''Strength: +10'' will do nothing<br />
|-<br />
| Strength n,<br />Dexterity n,<br />Constitution n,<br />Intelligence n,<br />Wisdom n,<br />Charisma n<br />
| Replaces the indicated ability score, which will appear in blue on the sheet while the bonus is active.<br />Do not use a colon. ''Strength: 10'' will do nothing<br />
|-<br />
| '''Skills'''<br />
| <br />
|-<br />
| Acrobatics +n,<br />Animal Handling +n,<br />Arcana +n,<br />Athletics +n,<br />Deception +n,<br />History +n,<br />Insight +n,<br />Intimidation +n,<br />Investigation +n,<br />Medicine +n,<br />Nature +n,<br />Perception +n,<br />Performance +n,<br />Persuasion +n,<br />Religion +n,<br />Sleight of Hand +n,<br />Stealth +n,<br />Survival +n<br />
| Adds the value to the indicated Skill roll. Note that in this case, the <code>+</code> and a colon are optional. <code>Acrobatics +5</code>, <code>Acrobatics 5</code>, <code>Acrobatics: +5</code>, <code>Acrobatics: 5</code> will all add <code>5</code> to the character’s Skill roll. For consistency and to guard against future functionality, it’s probably best to follow the format for ability scores, and use a plus sign with no comma: <code>Acrobatics +5</code>.<br />There is no Global Skill modifier<br />
|-<br />
| '''AC'''<br />
| <br />
|-<br />
| AC +n<br />
| By itself, <code>AC: 13</code> adds 13 to the character’s Armor Class. It does not replace it. <br /><br />If <code>Shield</code>, <code>Light Armor</code>, <code>Medium Armor</code>, or <code>Heavy Armor</code> is also in the mods field, it will change the calculation.<br />''<code>Light Armor, AC: 13</code>'' will give a formula of 13 + dex mod<br />''<code>Medium Armor, AC: 13</code>'' will give a formula of 13 + dex mod (max +2)<br />''<code>Heavy Armor, AC: 13</code>'' will give you flat AC 13<br />''Shield, AC: 13'' would add 13 to the your AC. The Shield keyword is superfluous in this case.<br />''<code>Shield, AC: 2</code>'' will just add 2 to the AC.<br />Finally, a bare modifier, such as for a Ring of Protection can just be written as <code>AC: +2</code> or <code>AC +1</code>.<br /><br />Shield or bare AC bonuses will stack with other armor mods on different items. You cannot equip multiple armors simultaneously, or have a custom armor equation on the settings tab and wear an armor. This will generate a flag.<br /><br />The + and a colon are semi-optional. <code>AC +5</code>, <code>AC: +5</code>, <code>AC: 5</code> will all work. However, <code>AC 5</code> will do nothing. For consistency and to guard against future functionality, it’s probably best to indicate a base AC as <code>AC: n</code> and a Shield as <code>AC +n</code>.<br />At this point, there is no way to differentiate between Ranged AC and Melee AC, though some magic items such as the ''Arrow Catching Shield'' make the distinction.<br />
|}<br />
<br />
<br />
<br />
<div style="clear: both"></div><br />
<br />
===(17) Features & Traits===<br />
[[File:5E OGL Sheet Features Traits.png|thumbnail|left|The Compendium Compatible itemized version of the Features & Traits section]]<br />
The '''Features and Traits '''-block is the place to store '''Class-''', '''Race-''' and '''Background Features''', '''Feats''', and other special notes about your character or of a certain piece of equipment or ability. When using the Charactermancer, the previously mentioned features appears in this section.<br />
<br />
This block can be set up to be <span style="font-family:Pictos;">i</span> [[Compendium|Compendium Compatible]] (where you can add repeating sections for individual items) or as one resizable free-text field to enter whatever you wish in here. You can adjust this block's behavior by going to the [[D&D 5E by Roll20#Settings Page|Settings Page]] of the sheet and going to the '''General Options'''-block to change whether this block uses the Simple or Compendium Compatible layout. <br />
<br />
When adding items to the Compendium Compatible version of this block, you have the <code>Name</code> field, a <code>Source</code>-field where you can choose between (Racial, Class, Feat, Background, or Other) , a <code>Source Type</code>-text field to describe the type, and then the multilined <code>Description</code>-textbox. Clicking on the <span style="font-family:Pictos;">y</span>(gear)-icon in the top right corner of the item will lock/unlock the item's editability. When locked down, a <span style="font-family:Pictos;">w</span>(chat bubble)-icon appears when you mouse over the feature/trait. Clicking on the <span style="font-family:Pictos;">w</span> will share this feature's description in the {{Text Chat}}.<br />
<br />
There presently isn't a means to format the raw text (italicize, bold, font alignment, etc) of the Simple version or in the Description section of either version of the Features & Traits block.<br />
<br />
You can drag-n-drop '''Feats''' from the compendium, even though they can't be selected in the Charactermancer on levelup.<br />
<br />
PC Features and Traits can be called using an ability roll:<br />
<code>%{selected|repeating_traits_$0_output}</code><br />
Simply increase the $0 value to access all Features and Traits listed on the character sheet, $1, $2, $3...<br />
<br />
<p style="clear:both;"></p><br />
<br />
==Bio Page==<br />
[[File:D&D5E-Roll20-BIO-tab.png|right|thumb|250px|The Bio Page of the PC Sheet]]The Bio page, opened by selecting "BIO" from the 4 buttons near the top right of the sheet, is comprised of free-form text fields that can be used to keep track of less "structured" information about your character. You can use this page to describe your character's appearance, keep track of who their allies are and what organizations they've worked for, and on this page is a section to supplement the inventory list, on the front page, with the "Treasure" section, where you can keep track of all the loot you find along your travels.<br />
===Bio Header===<br />
[[File:D&D5E-Roll20-Bio-header.png|550px]]<br /><br />
<br />
The header of the Bio page contains the basic run down of a character's physical appearance.<br />
*'''Character Name:''' This is carried over from every single PC Page and matches the character journal's name<br />
*'''Age:''' The character's current age<br />
*'''Size:''' The size classification for the race type (Medium for most cases)<br />
*'''Height:''' The character's height<br />
*'''Weight:''' The character's weight<br />
*'''Eyes:''' The character's eye color<br />
*'''Skin:''' The character's skin color<br />
*'''Hair:''' The character's hair color/style<br />
<br />
===Character Appearance===<br />
While the Bio Header describes the bare bone physical characteristics of a PC, this field is for fleshing out the visual peculiarities and/or cues of your character. Does you character have a piercing gaze? A stooped posture? Are they fancily dressed or are their clothes moth-eaten? In essence, this field is for everything and anything one would note about the character–from the equipment or garb they wear to how they comport themself.<br />
<br />
===Allies & Organization===<br />
This text field is for listing important or campaign relevant NPCs that the character may have a connection with. It's also for keeping track of faction allegiance. In the case of ''Dungeons & Dragons''' Forgotten Realms world, a PC could be a member of the Harpers or the Emerald Enclave, among other major factions who are all vying for power of the continent.<br />
<br />
===Character Backstory===<br />
This field is for listing your character's pre-campaign history, their relations, and the pertinent places they have been to in the past.<br />
<br />
===Additional Features & Traits===<br />
This text field is a continuation of the [[#.2817.29_Features_.26_Traits | Features & Traits]] section of the Core Page. The section on the Core Page is a good place for commonly utilized features of a character or briefly jotting down an abbreviated list. This field on the Bio page gives you more real estate to fully write down everything you need in whole.<br />
<br />
===Treasure===<br />
This text field is where you can list all the loot you've collected while searching bodies and delving through dungeons. Since much of these effects are transient and are likely to be used, given away, or sold to the highest bidder at the earliest opportunity, this may be preferable place to keep this list of items rather than adding them to the itemized Compendium Compatible Equipment section (if you have that version enabled).<br />
<br />
==Spell Page==<br />
[[File:D&D5E-Roll20-Spells-tab.png|right|thumb|400px|The Spell Page]]The Spell page, opened by selecting the "SPELLS" button from the four buttons near the top right of the sheet, is used to keep track of all of the powerful magics at your character's fingertips.<br />
<br />
===Spell Page Header===<br />
[[File:D&D5E-Roll20-Spells-header.png|550px]]On the Spells page Header you can set the ability modifier that will be used for casting spells. Selecting the Spellcasting Ability block will allow you to select an attribute from a dropdown, and this will be used in all relevant spell rolls. This attribute will be set automatically when you select a spell casting class. The next two blocks, the Save DC and Attack Bonus will be set automatically based on the class that is selected on the Core page.<br />
<br />
===Spellcasting Ability===<br />
The Spellcasting Ability modifier will automatically update, depending on the class you select on the Core page, to the correct ability modifier for your class. If, for some reason, you need to change this value you can click on the modifier listed in this section and it will give you a drop-down list of all available ability modifiers.<br />
<br />
===Spell Save DC & Attack===<br />
The Spell Save DC and Spell Attack Bonus sections cannot be changed manually, but are just a visual output of modifiers that will be happening behind the scenes. The Spell Attack Bonus is the number that will be added to all spell attack rolls, automatically.<br />
<br />
The Spell Save DC refers to the Save DC that enemies will have to beat when they are trying to dodge/resist your incoming spells. Say, Fred the Sorcerer casts Lightning bolt, and his Spell Save DC is 14. Any enemies hit by his attack will have to make a DEX save and try to beat 14. If they manage to beat the attack, then they are only grazed and take half of the damage. If they don't beat 14, then they take the full damage of the attack instead.<br />
<br />
===Spell Levels & Spells Per Day===<br />
The main section of the Spells page lists 10 sections, ranging from 0 to 9, representing the Cantrips (0) and spells level 1 - 9 where the level of the spell is listed in the triangle on the left of each section header. The number in the left square of the header represents the total number of Spell Slots, in other words, the maximum number of times a spell of this level can be cast in between long rests. This number will be set automatically depending on the level of your character, but can be modified by clicking the up or down arrow or just entering a number in the space provided. The number in the right-most box in the headers is the Slots Remaining value that can be used for you to keep track of the number of times you've cast a spell at this level.<br />
<br />
===Adding Spells===<br />
[[File:D&D5E-Roll20-Spells-Icons.png|framed|right]]<br />
When you drag spells from the <span style="font-family:Pictos;">i</span> [[Compendium]] to the sheet, a new spell entry will be added to the Spell Page under the appropriate level header. This will copy over all corresponding information linked to the spell, as well as creating an attack entry in the [[D%26D_5E_by_Roll20#.2811.29_Attacks_.26_Spellcasting|Attacks & Spellcasting]]-block on the "Core" page, if the spell can be used as an attack. The name of the spell will be listed to the left of the entry and to the right are icons for whether the spell is a Ritual (R), requires Concentration (C), and lists whether there is a Verbal (V), Somatic (S), or Material (M). There is also a circle at the far left of the entry that can be toggled to be filled in with red or left empty. This toggle represents spells that are Prepared for the day and are available for a player's convenience to help track this.<br />
<br />
You can manually add spells by selecting the <span style="font-family:Pictos;">&</span> under any of the Spell Level headings. This will present you with a blank template where you can enter all of the information about a spell. By default, the spell card only contains non-attack information about a spell. If the spell IS an attack you can change the "Output" selector from "Spellcard" to "Attack", this will show some additional input fields to fill out the attack information about the spell. Switching this input will also add an attack entry to the [[D%26D_5E_by_Roll20#.2811.29_Attacks_.26_Spellcasting|Attacks & Spellcasting]]-section on the [[#Core Page|Core page]] so this spell attack can also be cast from the main page. All of these sections are linked, so changing information in one place will also change the corresponding information in the other location. To save your edits, click on the gear icon at the upper right of the entry to collapse the spell entry.<br />
<br />
You can edit any spell at any time, by hovering your mouse over the entry to make a <span style="font-family:Pictos;">y</span> icon appear on the left. Clicking on the <span style="font-family:Pictos;">y</span> will roll out the spell once more to be edited.<br />
<br />
==Settings Page==<br />
[[File:D&D5E-by-Roll20-Settings-Page.png|thumb|right|400px|The Settings tab of the sheet, accessed from the '''<span style="font-family:Pictos;">y</span>''' icon ]]<br />
The Settings page, accessed by selecting the <span style="font-family:Pictos;">y</span>(gear) icon from the four buttons near the top right of the sheet, is where you can make changes to some parts of your character sheet that aren't represented on the other pages.<br />
<br />
===Class Options===<br />
In the class options section is where you have access to some important parts of your character, that usually are managed in the background. They are placed here so that, if needed they can be modified as well.<br />
<br />
'''Hit Dice:''' This section will be set automatically depending on the class chosen on the [[#Core Page|Core page]], but can be changed here by selecting the value and choosing a new one from the drop-down menu. This option is used whenever the "Hit Dice" section is used on the Core page.<br />
<br />
'''Carrying Capacity Modifier:''' This modifier allows you to increase the weight that a character can carry before they become encumbered.<br />
<br />
'''Global Magic Attack Modifier:''' This modifier will affect all spell attacks rolled from the sheet.<br />
<br />
'''Magic Caster Level:''' By default, a character's caster level is tethered to their class level. This option allows you to set the caster level manually, so you can have it differ from the character's class level. This will automatically change the Spell Slots Total for each spell level on the [[#Spell Page|Spells page]].<br />
<br />
'''Spell Save DC Mod:''' The Spell Save DC is normally a field you can't edit from the Spell page and is set by the character's class and level. This modifier allows you to alter that value.<br />
<br />
'''Spell Icons:''' This option will allow you to choose to turn off all the Spell Icons (R, C, V, S, & M), show them all, or only display only the ritual and concentration icons.<br />
<br />
'''Halfling Luck:''' Use this checkbox if your character is a Halfling that happens to take advantage of the Halfling Luck race feat. Using this feat will automatically re-roll any 1s rolled for attacks and skills or ability checks/saves.<br />
<br />
'''Arcane Fighter/Rogue:''' These checkboxes can be used to keep track of when your Fighter or Rogue-classed character actually has access to spells.<br />
<br />
===Multiclass Options===<br />
If you are taking advantage of the D&D 5E multiclassing you can keep track of it in this section. Any levels to your character's additional classes must be changed here, and will then be reflected in the header portion of the sheet. Once you've added additional classes in this section, any time you roll Hit Dice from the Core page it will ask you which classes hit dice you wish to use.<br />
<br />
Note: Be sure to not re-include your main class in this section, or your final level calculation will be incorrect.<br />
<br />
===Custom Class Options===<br />
If you are playing a class that is not part of the D&D 5E Compendium, you can input the important class information in this section, and checking the "Use Custom Class" checkbox will replace the main class selection with your custom built class.<br />
<br />
===Spell Slot Modifiers===<br />
This section allows you to manually modify how many spell slots your character has available for each spell level from 1 to 9.<br />
<br />
===Attribute Options===<br />
'''Attribute Modifiers:''' With this section you can manually adjust the individual Attribute Scores for Strength, Dexterity, Constitution, Intelligence, Wisdom, and Charisma.<br />
<br />
'''Initiative Modifier:''' Usually, your initiative modifier is just based off of your DEX modifier, but if you happen to find a magical item that enhances these rolls this is where you will put that bonus. This modifier will be used whenever the [[#.287.29_Armor_Class.2C_Initiative.2C_.26_Speed|Initiative]]-section is rolled on the Core page.<br />
<br />
'''Initiative Style:''' This setting allows you to select whether Initiative will be rolled with Advantage, Disadvantage, or rolled normally with a single d20 (default).<br />
<br />
'''Add DEX Tiebreaker to Initiative:''' If you would like to enable a tie breaker component to Initiative, this checkbox will enable adding your dexterity Attribute Score as a decimal value to your Initiative roll. So if you have a character with a dexterity attribute score of 14, your initiative modifier will change from a 2 to a 2.14.'<br />
<br />
'''Global Armor Class Modifier:''' This setting will modify your armor class and will be taken into account regardless of the equipment the character uses.<br />
<br />
'''Armor Class Tracking:''' There are three options available: The Automatic version that's default to the sheet where it adds 10 + your DEX modifer and then takes any armor equipped into account. A Custom version which expands out a formula upon selection where you can input your own formula for armor tracking, or you can turn Off Armor Tracking entirely. When turned off, you will need to manually adjust the Armor Class field on the Core page.<br />
<br />
===Save Options===<br />
'''Save Modifiers:''' With this section you can manually adjust the individual Save modifiers for Strength, Dexterity, Constitution, Intelligence, Wisdom, and Charisma.<br />
<br />
'''Death Save Modifier:''' A normal death save is usually just a D20 against a dc of 10, but if you're lucky enough to have a bonus to death saves, this is where you will put your bonuses. This modifier will be represented any time a "Death Save" is rolled from the Core page.<br />
<br />
'''Global Saving Throw Modifier:''' If you have an affect that would modify all saving throws, this option makes it easier to adjust your Save modifiers than having to go in and change each one individually. This modifier will be used every time any save is rolled from the sheet.<br />
<br />
===Skill Options===<br />
If your class offers the ability to achieve "Expertise" in a skill, or if you are using a Bard with the "Jack of All Trades" feat, this is where you will make these adjustments. There is also a section to add flat modifiers to any of your skills if your character has an archetype ability like Remarkable Athlete or a feat that adds a flat bonus to a skill. You can add expertise to any skill by clicking the value next to it and choosing "Expertise" from the drop-down menu. If your Bard has the Jack of All Trades feat, you can check the checkbox at the bottom of this section and it will automatically give half of your character's proficiency points to any skill check that doesn't have full proficiency.<br />
<br />
'''Passive Perception Modifier:''' This option will add a bonus to a character's Passive Perception which is not something you can change directly from the Core page of the sheet.<br />
<br />
===General Options===<br />
The General Options section has some important options that deal more with how the sheet works, rather than actual character creation. Most importantly, the NPC checkbox at the top, which will change the sheet to be the NPC version which is shaped to more easily track an NPC's information.<br />
<br />
'''Roll Queries - Always/Toggle/Query/Never Roll Advantage:''' This option will change how advantage is rolled for all attacks. It defaults to always roll advantage, which means that every time an attack is rolled it will roll twice and present the outcome of both rolls. This is useful for both advantage and disadvantage, otherwise you can just choose either the left or the right to be the default roll. Toggle adds a set of buttons at the top of the sheet to manually switch your advantage options between rolls. If Query is chosen, every time a roll is made it will ask you whether or not it's advantage. If Never is chosen, then it will always roll just a single dice per attack roll.<br />
<br />
'''Whisper Rolls to GM:''' Like above, you have the option to Never/Toggle/Query/Always whisper rolls to the GM. When this option is enabled, the attack roll will only be whispered to the GM and not made public.<br />
<br />
'''Auto Damage Roll:''' By default, damage rolls will not be rolled automatically, but only when you click the attack in the chat window. This is useful because you can choose to only roll damage when an attack hits. Using this option you can make the character always roll damage with every attack.<br />
<br />
'''Core Die Roll:''' You can change the core die (by default it is 1d20) to something else entirely here.<br />
<br />
'''Proficiency Bonus:''' By default, the character's Proficiency Bonus is calculated by class level. This setting allows you choose to calculate this bonus via By Level (the default), via a Proficiency Die as described in the Dungeon Master's Guide, or a Custom calculation which rolls out a field to enter a roll formula for the bonus.<br />
<br />
'''Global Save/Skill/Attack/Damage Modifier Field:''' This series of checkboxes will add new entries to the Saving Throws, Tools Proficiencies & Custom Skills, and Attacks & Spellcasting blocks respectively to add global modifiers (like if a character is under the effects of a Bless or Guidance spell). Each entry will have a Global label in grey at the bottom of its entry and a field to enter the modifier bonus. If you include a word in brackets with the bonus formula (ex. "1d4[Bless]"), the word enclosed in the brackets will appear when you mouse over a roll to see it's formula.<br />
<br />
'''Add Character Name to Templates:''' This option allows you to turn this on or off. When it is on, the character's name is listed in the roll template when rolls are made from the sheet. If the character sheet in question is for an NPC, you will likely want to have this off so the rolls don't accidentally show your hand of what sort of monster your party is facing. This setting is off by default.<br />
<br />
'''Auto Level Calculations:''' This option allows you to turn this on or off. When it is on, adjusting the character's class level will automatically update the character's proficiency bonus, Hit Dice, and spell Slot totals (if the class is a spellcaster).<br />
<br />
'''Encumbrance:''' This option dictates how encumbrance is handled on the Equipment block of the Core page. This requires your Inventory to be set to "Compendium Compatible" to automatically calculate and track the weight of your character's backpack if you enter the weight values for any of the items in your Equipment list. When your character becomes encumbered, and depending on its severity, the words ENCUMBERED, HEAVILY ENCUMBERED, or IMMOBILE will display in red underneath the TOTAL WEIGHT value. This setting has three options: Simple Encumbrance Rules, Variant Encumbrance Rules, or not follow Encumbrance rules at all by toggling it off from this.<br />
<br />
'''Inventory:''' With this option allows you to either have your Equipment block be "Compendium Compatible" or "Simple". The Simple version of the Equipment block will give you single text field to log your inventory. The Compendium Compatible version tracks weight, quantity, and attack options in an itemized list for every equipment item you add to the block.<br />
<br />
'''Features & Traits:''' This option can set the Features & Traits block to be either a single text field or a repeated section that will be Compendium Compatible to list traits and features in an itemized list.<br />
<br />
'''Proficiencies & Languages:''' This option can set the Proficiences & Languages block to be either a single text field or a repeated section that will be Compendium Compatible to list traits and features in an itemized list.<br />
<br />
'''Ammo Tracking (API Required):''' When using the 5th Edition OGL Companion API Script in your game (Pro Subscriber feature), you can set attacks to weapons using ammunition to automatically subtract from their tally in their Resource block. So if your character is equipped with a bow, rolling its attack will automatically remove an arrow from its Resource block.<br />
<br />
===Transition Options(outdated)===<br />
{{mbox | text = This feature doesn't seem to exist on the sheet any longer, so the info in this section is outdated}}<br />
<br />
If your campaign previously used the [https://wiki.roll20.net/DnD5e_Character_Sheet#Intro Community Contributed] or [https://wiki.roll20.net/index.php?title=DnD5e_Shaped_Character_Sheet&oldid=11112#General_Information Shaped Legacy] 5th Edition Character Sheets and you are swapping over to this one, we have an automated conversion tool that will clear or merge elements left over from those two sheets. This procedure can only be done ''once'' and can not be undone. It is recommended that you make a copy of your campaign first before attempting a sheet transition.<br />
<br />
There is also a checkbox that hides this feature entirely from the sheet. If you hide this by mistake, you can gain access to it again by creating a new character journal.<br />
<br />
=The NPC Sheet=<br />
''See Also:'' '''[[D&D5E by Roll20 NPC Attributes]]'''<br />
<br />
One of the most useful parts of the D&D 5E by Roll20 Character Sheet is that it contains both a PC sheet ''AND'' an NPC sheet. An NPC doesn't normally require the depth a PC sheet needs, so the NPC sheet is a much more slimmed down character sheet that doesn't require multiple pages like its PC counterpart. You can access this version of the sheet by going to the Settings Page, by clicking the gear icon near the top right of the sheet, and then checking the NPC checkbox. This will switch the sheet to the NPC version. You can switch back at any time by unchecking the NPC option under General Options on the new page.<br />
<br />
==NPC Options==<br />
[[File:5E_OGL_Sheet_NPC_Options.png|right|thumb|250px|The NPC Options Section]]This is the area where all of the NPC's stats will be entered, it covers everything from the NPC's name, to how strong or quick or smart it is, to what languages it speaks. Most of the fields in this section are just text fields used to keep track of information about the NPC. All of the information entered in these fields will be visible in the stat block once the NPC options are hidden. <br />
<br />
<br />
Any text that appears in light grey is placeholder text. It's there to offer you an example of what the content would be for any given field. <br />
<br />
By default, no skill or ability checks will show up in the NPC's stat block. Once you've added a value to the corresponding skill or ability save, they will appear. If for some reason the NPC will have to make a check with a skill or ability it does not have any bonus in, you can enter a 0 as the modifier for that check and it will add it to the list in the stat block below.<br />
<br />
The XP of an NPC auto-calculates based on its given challenge rating.<br />
<br />
If the NPC is a spellcaster, you can check the checkbox beside '''SPELLCASTING NPC''' and this will add a spell list section that utilizes the spell list and its functionality from the PC version of the sheet.<br />
<br />
At default, you can add Traits and Actions in their respective places after the Challenge Rating and XP area of the Stat Block. For Reactions and Legendary Actions, you need to enable them from the NPC Options section. For Reactions, check off the '''HAS REACTIONS''' checkbox. This will add a new sections to the Stat Block for you to add Reactions to. If an NPC is a monster with Legendary Actions then you must enter the number of actions that monster has access to each turn in the '''LEGENDARY ACTIONS:''' field. Once you add a number here, an additional section will appear in the stat block below, where you can add the specific legendary actions that the monster is able to do.<br />
<br />
The NPC sheet supports Compendium drag & drop. If you want to add a new monster to your game just drag the monster from the <span style="font-family:Pictos;">i</span> [[Compendium]]-tab of the [[Sidebar]] and drop it to anywhere on the Tabletop. This will automatically create a new journal entry named the same as the Compendium entry and will copy all of the information on that compendium page directly into the new sheet. If you have purchased any of the Compendium expansions that expands on the available NPCs like the Monster Manual or Volo's Guide to Monster, a token of that NPC will be added to the Tabletop that will have its stats automatically set and linked to the new journal entry.<br />
<br />
{{mbox | text = '''Note:''' If you already have a journal entry in your {{journal}}-tab with the exact same name as the <span style="font-family:Pictos;">i</span> [[Compendium]] entry, the drag and drop will not work as this automation will stop to prevent overwriting existing content the user has already created. If a drag and drop of an NPC Compendium page does not create a journal entry, run a search for that NPC's name in your Journal to see if an entry already exists. If you do not want to delete the older entry, renaming it will allow the drag and drop to work as expected.}}<br />
<br />
===General Options===<br />
Within the NPC Options section, directly below the Legendary Actions field, is the General Options that are featured on the PC Sheet: NPC checkbox, WHISPER ROLLS TO GM, and the AUTO DAMAGE ROLL options. <br />
<br />
*NPC checkbox<br />
*WHISPER ROLLS TO GM<br />
*AUTO DAMAGE ROLL<br />
*NPC NAME IN ROLLS<br />
*ADD DEX TO TIEBREAKER TO INITIATIVE<br />
<br />
Unchecking the NPC checkbox from here will revert the sheet back to the PC Sheet.<br />
<br />
===Hiding NPC Options===<br />
Once all of the desired information has been entered, you can click the <span style="font-family:Pictos;">y</span>(gear) icon at the top right to hide this section. This leaves behind just the NPC's stat block where you can make all of your rolls from. You can re-open this section to edit the information at any time by clicking on the <span style="font-family:Pictos;">y</span> icon again. It's in the same location regardless if you're looking at NPC Options or the NPC stat block.<br />
<br />
==The NPC Stat Block==<br />
[[File:5E OGL Sheet NPC v2.png|right|thumb|250px|An NPC stat block for a griffon]]Following NPC Options is the NPC Stat Block that is built off of what you input in the NPC Options section. This area may look very similar to a stat block you may find in a monster bestiary or published adventure.<br />
<br />
<br />
Any section of the stat block that has a corresponding roll will have click-able text. For example, if the NPC has to make a CON check, you can click the CON attribute to roll a CON check with all of the required modifiers automatically included. If you added a value to one of the skill modifier fields then that skill will show up in the NPC's "Saving Throws" list where you can click it to make a saving throw roll using that skill's modifier.<br />
<br />
The first section of the Stat Block mirrors all the information you added in the NPC Options section. This content is meant exclusively for rolling and can not be edited directly. You will need to change them from the NPC Options section.<br />
<br />
===Traits===<br />
Traits are pieces of information about an NPC that isn't covered by the NPC options section. These are entered directly onto the NPC's stat block. If you click the "<span style="font-family:Pictos;">&</span>" button that appears right below the "Senses/Languages/Challenge Rating" section it will add a blank entry where you can add a single trait for that NPC. Each Trait Entry features a bold title field which is then followed by a larger text box for the description of the trait. You can add any number of Traits for any NPC.<br />
<br />
===Actions===<br />
NPC actions can be used for any number of things. Each entry initially offers an Action Name field as well as a large text field for the Action description. The checkbox for ATTACK, once checked, adds more structured data fields needed for an attack roll (Type, Range/Reach, To Hit bonus, Target, Damage Roll, and Damage Type). To add a new entry you will select the <span style="font-family:Pictos;">&</span> button that appears below the Actions section. Once all of this is complete you can click the <span style="font-family:Pictos;">y</span>(gear) icon at the top of this entry to hide the input fields, leaving just the action text. You can show this information, or roll the attack, in the chat box by clicking the text for the action. If you need to make further modifications to any action you can hover over the row you wish to edit, then click on the <span style="font-family:Pictos;">y</span>(gear) icon again. This will show all of the action information input fields again. You can add any number of Actions for any NPC.<br />
<br />
===Bonus Actions===<br />
NPC bonus actions are typically not listed on the sheet, and are usually referenced in the Traits section. However, if a player wishes to use this section, it is available if the 'Bonus Action' checkbox is selected. The fields work the same as the Actions section.<br />
<br />
===Reactions===<br />
Once enabled from the NPC Options section, a new heading labeled "Reactions" and its relevant section is added to the stat block that allows you to add Reactions. These entries operate just like Traits.<br />
<br />
===Spells===<br />
Once enabled from the NPC Options section, a new heading labeled "Spells" and its relevant section is added to the stat block that allows you to add Spells. These entries will operate identically to how Spells are added and handled on the PC Sheet with the one noted exception that there is only a single column of spell entries. You can drag spells from the Compendium to add spell entries just like you would with the PC's Spell sheet. Any and all spells added to the character sheet are shared between the NPC and the PC versions.<br />
<br />
===Legendary Actions===<br />
If a number value is added to the LEGENDARY ACTIONS field in the NPC Options section, the Legendary Actions heading and section is added at the very bottom of the stat block and lists some verbiage on how many actions are available to be used on a given turn. This number is dictated by what you entered in the NPC Options. These entries operate the same way as Traits.<br />
<br />
==Rolling for Initiative for NPCs==<br />
There are two ways to roll for Initiative on the NPC sheet. You can click on the NPC's Name to roll for Initiative or you can roll from the die icon labeled INIT that is listed to the right of the Armor Class and Hit Points section of the NPC sheet, towards the top. If you have the Turn Tracker tool open, having the NPC token selected while rolling Initiative will automatically add the NPC and its initiative roll to the tracker. Creatures on the GM layer that are added to the tracker in this fashion will have their entries hidden from the players.<br />
<br />
<br />
You can also create a global Macro that will pop up as a Token Action button in the upper left hand corner of the tabletop every time a token is selected. This will allow you to roll without looking at the NPC sheet at all. The macro formula should look just like this:<br />
<br />
<code>%{selected|npc_init}</code><br />
<br />
=Advanced Use=<br />
<br />
===Custom Skills and Stats===<br />
You can set up any number of custom skills or rolls from the [[#Tool Proficiencies|Tool Proficiencies]] section just underneath the skill section on the Core tab. [[#Class & Other Resources|The Resources]] section is also useful for tracking custom stats to your campaign, game setting, or home-brew rules. There are also various options available from the Settings page to modify attributes, skills, saves, spells, and more.<br />
<br />
===Target Roll Buttons===<br />
A useful way for GMs and Players to reference their abilities is by dynamically setting up a handful of macros that can be used on a token linked to a character, rather than having to roll directly from the sheet. To do this, you'll set up a global macro from the {{Collections}}-tab. You can also write these directly in the {{Text Chat}}.<br />
<br />
In the examples, the <code>selected</code> part can be replaced with <code>target</code>, a character's name, or it's character ID.<br />
<br />
Here are some examples:<br />
<br />
'''PC'''<br />
* Attributes: <code>%{selected|strength}</code>, <code>%{selected|strength_save}</code> | Will roll the Strength Check and Strength Save for the selected [[token]](if the [[Link Token|token is linked to a sheet]])<br />
* <code>%{selected|acrobatics}</code><br />
* <code>%{selected|initiative}</code><br />
* <code>%{selected|death_save}</code><br />
* <code>%{selected|hit_dice}</code><br />
<br />
'''NPC'''<br />
* <code>%{selected|npc_init}</code><br />
* <code>%{selected|npc_str}</code><br />
* <code>%{selected|npc_stealth}</code><br />
* <code>%{selected|npc_hpformula}</code><br />
====Dynamic References to Repeating Sections====<br />
The example we'll be using today is setting up the 1st NPC action:<br />
<code>%{selected|repeating_npcaction_$0_npc_action}</code><br />
Now whenever you use this macro it will roll the first NPC action of whichever NPC token you have selected. You can set up a roll for each action by incrementing the 0 by 1 for each action you wish to add (I.E. <code>$1</code>, <code>$2</code>, <code>$3</code>). Here is a list of important repeating section rolls and their formulas:<br />
<br />
* Player Attack/Spell Attack <code>%{selected|repeating_attack_$0_attack}</code><br />
* Player Attack/Spell Damage <code>%{selected|repeating_attack_$0_attack_dmg}</code><br />
* Player Attack/Spell Critical Damage <code>%{selected|repeating_attack_$0_attack_crit}</code><br />
* Player Global DMG mod <code>%{selected|repeating_damagemod_$0_global_save}</code><br />
** Attr names: <code>global_damage_name</code>, <code>global_damage_damage</code>, <code>global_damage_critical_damage</code>, <code>global_damage_type</code><br />
* Proficiencies <code>%{selected|repeating_proficiencies_$0_output}</code><br />
* Tool/Custom Skill <code>%{selected|repeating_tool_$0_tool}</code><br />
* Traits/Feats: <code>%{selected|repeating_traits_$0_output}</code><br />
<br />
* Spellbook Cantrip <code>%{selected|repeating_spell-cantrip_$0_spell}</code><br />
* Spellbook Level 1 <code>%{selected|repeating_spell-1_$0_spell}</code><br />
* Spellbook Level 2 <code>%{selected|repeating_spell-2_$0_spell}</code><br />
* Spellbook Level 3 <code>%{selected|repeating_spell-3_$0_spell}</code><br />
* Spellbook Level 4 <code>%{selected|repeating_spell-4_$0_spell}</code><br />
* Spellbook Level 5 <code>%{selected|repeating_spell-5_$0_spell}</code><br />
* Spellbook Level 6 <code>%{selected|repeating_spell-6_$0_spell}</code><br />
* Spellbook Level 7 <code>%{selected|repeating_spell-7_$0_spell}</code><br />
* Spellbook Level 8 <code>%{selected|repeating_spell-8_$0_spell}</code><br />
* Spellbook Level 9 <code>%{selected|repeating_spell-9_$0_spell}</code><br />
<br />
'''NPC'''<br />
* NPC Traits/Abilities<code>%{selected|repeating_npctraits_$0_npc_roll_output}</code><br />
* NPC Actions/Attacks<code>%{selected|repeating_npcaction_$0_npc_action}</code><br />
* NPC Attack Damage<code>%{selected|repeating_npcaction_$0_npc_dmg}</code><br />
* NPC Attack Critical Damage<code>%{selected|repeating_npcaction_$0_npc_crit}</code><br />
* NPC Bonus Actions<code>%{selected|repeating_npcbonusaction_$0_npc_action}</code><br />
* NPC Legendary Actions<code>%{selected|repeating_npcaction-l_$0_npc_action}</code><br />
* NPC Mythic Actions<code>%{selected|repeating_npcaction-m_$0_npc_action}</code><br />
* NPC Spells<code>%{selected|repeating_spell-npc_$0_spell}</code><br />
<br />
===Directly Referencing Attributes===<br />
You can discover the name of most of the attributes in the sheet by hovering over them. After a couple of seconds a title will pop up and tell you how to referencing them. You can call attributes in an Ability Rolls by using <code>@{attributename}</code>. If you want to directly reference it in a roll that isn't saved on the sheet, you need to specify the character's name, or use either the <code>selected</code> or <code>target</code> key works.<br />
<br />
'''Examples:'''<br />
* <code>/em attempts to grapple and gets [[1d20+@{strength_mod}]]</code> custom [[Journal#Attributes_.26_Abilities_Tab|Ability call]], saved in the "attributes and abilities" tab of the character sheet.<br />
* <code>/r 1d20+@{Alice|strength_mod}+@{Alice|pb}</code> macro that calls a specific character<br />
* <code>/em have @{selected|hp} out of @{selected|hp|max} left.</code> macro that uses stats from a token(token must be selected before rolling)<br />
* <code>The Enemy's AC is @{target|npc_ac}</code> macro prompt the user to select a target token on the map, and uses it's stats.<br />
<br><br />
<br />
See [[Macros#Attribute_Macros]] for further general details/examples on the syntax.<br />
====PC====<br />
Here are a list of some of the more important stats:<br /><br />
<br />
'''Attributes/Saves:'''<br />
<br />
* Str: <code>strength, strength_mod, strength_save_bonus</code><br /><br />
* Dex: <code>dexterity, dexterity_mod, dexterity_save_bonus</code><br /><br />
* Con: <code>constitution, constitution_mod, constitution_save_bonus</code><br /><br />
* Int: <code>intelligence, intelligence_mod, intelligence_save_bonus</code><br /><br />
* Wis: <code>wisdom, wisdom_mod, wisdom_save_bonus</code><br /><br />
* Cha: <code>charisma, charisma_mod, charisma_save_bonus</code><br />
<br><br />
'''Skills:'''<br />
<br />
<code>athletics_bonus<br /><br />
acrobatics_bonus<br /><br />
animal_handling_bonus<br /><br />
arcana_bonus<br /><br />
deception_bonus<br /><br />
history_bonus<br /><br />
insight_bonus<br /><br />
intimidation_bonus<br /><br />
investigation_bonus<br /><br />
medicine_bonus<br /><br />
nature_bonus<br /><br />
perception_bonus, passive_wisdom<br /><br />
performance_bonus<br /><br />
persuasion_bonus<br /><br />
religion_bonus<br /><br />
sleight_of_hand_bonus<br /><br />
stealth_bonus<br /><br />
survival_bonus<br /><br />
</code><br />
<br />
'''AC, Proficiency, HD etc'''<br />
<br />
<code>pb</code>(Proficiency Bonus)<br><br />
<code>inspiration</code><br><br />
<code>ac<br /><br />
initiative_bonus<br /><br />
speed<br /><br />
hp, hp|max, hp_temp<br /><br />
hit_dice, hit_dice|max, hitdietype<br /><br />
weighttotal<br /><br />
</code><br />
<br />
'''Spells'''<br />
<br />
<code>spell_save_dc, spell_attack_bonus<br /><br />
lvl1_slots_total, lvl1_slots_expended<br /><br />
lvl2_slots_total, lvl2_slots_expended<br /><br />
lvl3_slots_total, lvl3_slots_expended<br /><br />
lvl4_slots_total, lvl4_slots_expended<br /><br />
lvl5_slots_total, lvl5_slots_expended<br /><br />
lvl6_slots_total, lvl6_slots_expended<br /><br />
lvl7_slots_total, lvl7_slots_expended<br /><br />
lvl8_slots_total, lvl8_slots_expended<br /><br />
lvl9_slots_total, lvl9_slots_expended<br /><br />
</code><br />
<br />
Spells, repeating sections:<br><br />
<code>repeating_spell-cantrip<br><br />
repeating_spell-1<br><br />
repeating_spell-2<br><br />
repeating_spell-3<br><br />
repeating_spell-4<br><br />
repeating_spell-5<br><br />
repeating_spell-6<br><br />
repeating_spell-7<br><br />
repeating_spell-8<br><br />
repeating_spell-9</code><br> <br />
<br />
Cantrip stats(most should also work for lvl.1-lvl.9):<br><br><br />
Full statname is spell level + (rowID or row number) + attribute name, e.g. <code>repeating_spell-1_$0_spellname</code> is the spell name of your first Lvl 1 spell, <code>repeating_spell-4_$1_spelldescription</code> is the description of your second lvl.4 spell.<br />
<br />
<code>spellname<br><br />
spellrange, spellcastingtime, spelltarget, spellduration<br><br />
spellschool<br><br />
spellritual<br><br />
spellconcentration<br><br />
spellcomp_v, spellcomp_s, spellcomp_m<br><br />
spellcomp_materials<br><br />
spell_ability<br><br />
spelloutput<br><br />
spellattack<br><br />
spelldamage, spelldamagetype, spelldamage2, spelldamagetype2<br><br />
spellhealing<br><br />
spelldmgmod, spell_damage_progression<br><br />
spellsave, spellsavesuccess<br><br />
spelldescription<br><br />
spellclass, spellsource</code><br />
<br />
'''Items'''<br><br />
<code>cp sp ep gp pp</code><br><br />
(copper pieces, silver, gold, electrum, platinum)<br />
<br />
<code>repeating_inventory_$#_itemcount<br><br />
repeating_inventory_$#_itemname<br><br />
repeating_inventory_$#_itemweight<br><br />
repeating_inventory_$#_equipped<br><br />
repeating_inventory_$#_useasresource<br><br />
repeating_inventory_$#_hasattack<br><br />
repeating_inventory_$#_itemproperties<br><br />
repeating_inventory_$#_itemmodifiers<br><br />
repeating_inventory_$#_itemcontent</code><br><br />
<br />
* <code>equipped</code>, <code>useasresource</code>, <code>hasattack</code> are checkboxes, with value 1 if checked.<br />
* <code>itemmodifiers</code> is for of item changes any stats, like <code>AC +2</code> adding +2 to AC when equpped.<br />
* <code>itemcontent</code> is the item description<br />
<br><br />
'''The class_resource and the other_resource'''<br><br />
<br />
<code>class_resource</code> and <code>other_resource</code> are static resources. That is to say, you need to keep in mind that they are NOT a part of the repeating section, even though it definitely looks that way on the character sheet.<br><br />
<br />
You use these to access them<br />
<br />
<code>class_resource</code><br><br />
<code>class_resource_max</code><br><br />
<code>class_resource_name</code><br><br />
<code>other_resource</code><br><br />
<code>other_resource_max</code><br><br />
<code>other_resource_name</code><br><br />
<br />
'''The repeating resources'''<br><br />
<br />
Any resources that appear beneath the "class resource" and the "other resource" are a part of the "repeating resources" section. This section is known for being confusing for beginners, so it deserves a bit of clarification.<br />
<br />
First, keep in mind that this is one section (not two sections, as people often think), and that "repeating_resource" is its section prefix.<br />
<br />
Second, keep in mind that you need to skip past the row with the "class resource" when you're figuring out the address of the row that you want to refer to. So basically, if you want to refer to the row that is directly below the row with the "class_resource", then you would add "_$0" (to form "repeating_resource_$0"). And then the next row after that is "_$1", and so on.<br />
<br />
Third, keep in mind that if you add "_resource_left" (to form "repeating_resource_$0_resource_left"), then you are specifying that you are talking about the CURRENT VALUE of the leftmost resource in that row. And if you add "_resource_left_max", then you are specifying that you are talking about the MAX VALUE of the leftmost resource in that row.<br />
<br />
Here is a complete list of all the fields that you can access in the "repeating_resource" section. Just replace the "#" character with which row you want to access.<br />
<br />
<code>repeating_resource_$#_resource_left</code><br><br />
<code>repeating_resource_$#_resource_left_max</code><br><br />
<code>repeating_resource_$#_resource_left_name</code><br><br />
<code>repeating_resource_$#_resource_right</code><br><br />
<code>repeating_resource_$#_resource_right_max</code><br><br />
<code>repeating_resource_$#_resource_right_name</code><br><br><br />
<br />
<br />
'''Features/Class Traits'''<br />
<br />
<code>repeating_traits_$0_output<br><br />
repeating_traits_$#_name<br><br />
repeating_traits_$#_source<br><br />
repeating_traits_$#_source_type<br><br />
repeating_traits_$#_description<br><br />
</code><br />
<br />
'''Other/Settings:'''<br />
<br />
<br><br />
<code><nowiki>wtype</nowiki></code> (whisper type, can have one of these values:)<br />
* <code><nowiki></nowiki></code> (empty for never whisper)<br />
* <code><nowiki>@{whispertoggle}</nowiki></code> (show the buttons on sheet that can toggle between options)<br />
* <code><nowiki>?{Whisper?|Public Roll,|Whisper Roll,/w gm }</nowiki></code><br />
* <code><nowiki>/w gm</nowiki></code> (always whisper)<br />
<br />
<br />
'''Global modifiers'''<br />
<br />
* <code>repeating_savemod_$0_global_save_roll</code><br />
* <code>repeating_skillmod_$0_global_skill_roll</code><br />
* <code>repeating_tohitmod_$0_global_attack_roll</code><br />
* <code>repeating_damagemod_$0_global_damage_damage</code><br />
<br />
====NPC====<br />
Some stats are the same as for PCs<br />
<br />
<code>npc_name<br><br />
npc_ac<br><br />
hp, hp|max<br><br />
npc_speed<br><br />
npc_challenge<br><br />
npc_xp</code><br />
<br />
Attributes: <code>strength_base, strength_mod</code> (same as PCs)<br />
Saves:<br />
<br />
<code>npc_str_save_base</code>,<code>npc_dex_save_base</code>, <code>npc_con_save_base</code>,<code>npc_int_save_base</code>,<code>npc_wis_save_base</code><code>npc_cha_save_base</code><br />
Skill bonus:<code>npc_acrobatics_base</code>, <code>npc_animal_handling_base</code> etc.<br />
<br />
Damage/Conditions stuff:<br />
<br />
<code>npc_vulnerabilities<br><br />
npc_resistances<br><br />
npc_immunities<br><br />
npc_condition_immunities</code><br />
<br />
Spells:<br />
<br />
<code>npcspellcastingflag</code> (set to "1" if caster, empty otherwise) <br />
<code>spellcasting_ability</code><br />
<code>globalmagicmod </code> (global magic attack modifier)<br />
<code>caster_level</code><br />
<code>spell_dc_mod</code> (spell save DC mod)<br />
<br />
Spells are identical to PC section<br />
<br />
Other:<br />
whisper is same as PCs<br />
<br />
<code>npc_name_flag</code> (show/hide npc name in rolls, value is either <code><nowiki>{{name=@{npc_name}}}</nowiki></code> or <code>0</code>)<br />
<br />
<br />
<sup>Note: anything with the Suffix of <code>|max</code> requires some form of Prefix, such as <code>selected|</code> making the call for such a thing look something along the lines of <code>@{selected|hp|max}</code>. The <code>|max</code> Suffix specifically calls the box on the right of the selected Attribute's Line, for example, you could fill in the Weight Total's 2nd Box with <code>@{strength}*15</code> & whenever you call <code>@{selected|weighttotal|max}</code> it will tell you your 5e standard Maximum Carry Capacity for your current Strength Score.<br />
<br />
===Custom AC Items===<br />
You can add pieces to your inventory and manually give them AC or magic bonuses that will figure into their calculations automatically. Inside the item options is a section for "MODS:". Add <code>Ac +1</code> to add an armor class bonus.<br />
<br />
===Roll Templates===<br />
''Main Article:'' '''[[D&D 5e by Roll20 Roll Templates]]'''<br />
<br />
The '''D&D5E by Roll20''' Character Sheet also includes a series of [[Roll Templates]] that you can use to dress up your own custom macros. Roll Templates provide additional layout and styling options for the display of roll results.<br />
<br />
{{ex}}<br />
[[File:5e-rolltemplate-ex1-2021.png|200px|right|none]]<br />
Rolls stealth for selected npc token, using it's stealth proficiency.<br />
<code><nowiki>/w gm &{template:npcatk} {{attack=1}} {{name=Shadow}} {{rname=Shadow Stealth}} {{rnamec=Hide}} {{r1=[[@{selected|d20}+@{selected|npc_stealth} + 6]]}} {{always=1}} {{r2=[[@{selected|d20}+@{selected|npc_stealth} + 6]]}} {{description=While in dim light or darkness, the shadow can take the Hide action as a bonus action. Its stealth bonus is **also** improved to +6 }}</nowiki></code><br />
<br />
===Magic Missile Spell===<br />
{| role="presentation" class="wikitable mw-collapsible mw-collapsed" style="float:right; margin-left: 10px;margin-right: 60px;"<br />
| Image of the Spell's settings<br />
|-<br />
| [[File:Magic-Missile-5E-2020.png|right|frame|The Magic Missile Spell]]<br />
|}<br />
<br />
RAW, Magic Missile is rolled once, and the single roll is then used for each hit. So by default the spell rolls <code>1d4+1</code>. (See [[Talk:D&D 5E by Roll20#Old Magic Missile Discussion]] for more info.)<br />
<br />
You can modify the spell to instead roll 3d4+3 at first level, and then in the ''HIGHER LVL CAST DAMAGE'' section, set it to <code>1d4+1</code>.<br />
<br />
To automatically use higher-level spell slots with Magic Missile, you have to write a 0 into the ''HIGHER LVL CAST DAMAGE'' section of the spell and select any die. It will show the box for selecting higher-level spell slots when launching Magic Missile, but since it multiplies the higher-level damage cast by 0, the added roll doesn't show up in the chat, making it roll a single die for every missile while using any level spell slot.<br />
<br />
=API=<br />
{{pro only|section}}<br />
[[API:Introduction|API Scripts]] allow for greater customization and functionality to how Roll20 operates beyond what it can do at default. This section will list some info on using various APIs that interact with the character sheet.<br />
<br />
Example of APIs from the One-Click Install menu, that designed to be used with the '''D&D 5E by Roll20''' sheet:<br />
* '''5E BattleMaster'''<br />
* '''5E Resting in Style'''<br />
* '''CashMaster'''<br />
* '''Concentration'''<br />
* '''[[Script:It's a Trap|It's a Trap! -- D&D 5E Generic]] (should detect automatically what sheet is used)<br />
** {{repo|Roll20/roll20-api-scripts/tree/master/ItsATrap_theme_5E_Generic#readme readme}}<br />
* '''ShortRest'''<br />
* '''SpellMaster'''<br />
* '''WildShape'''<br />
<br />
A good number of the more general APIs have built in settings for configuring them for usage with the 5E sheet, such as '''GroupInitiative''', '''GroupCheck''', '''Experience Tracker''', '''[[PowerCards]]''' <br />
<br />
* '''[[GroupCheck]]:''' <code>!group-check-config --import 5E-OGL</code> will configure the API for use with this sheet<br />
* '''[[GroupInit|GroupInitiative]]:''' before use, API need to be configured for the sheet, either through the menu preset, or using the command: <code>!group-init --add-group --Bare </code><br />
* '''CombatMaster:''' is by default configured with conditions for D&D 5E<br />
* '''[[ChatSetAttr]]:''' API that can create, edit, & delete stats on sheets. Example: [[Script:ChatSetAttr#Add_new_thing_to_Repeating_Section|Adding a new magic item to a sheet]], with one chat command <br />
* '''[[Script:Ammo]]''' can be used for updating ammo & spellslots when used<br />
<br />
==Utilizing the ''5th Edition OGL by Roll20 Companion'' API Script==<br />
'''{{repo|Roll20/roll20-api-scripts/tree/master/5th%20Edition%20OGL%20by%20Roll20%20Companion 5th Edition OGL Companion}}'''is an official companion script for the "D&D 5E by Roll20" character sheet. The Companion currently supports Ammo Tracking, Automatic NPC Tokens, Automatic Death Save Tracking, and Automatic Spell Slot Tracking. <br />
<br />
{{mbox | text = Installing & creating [[API]] Scripts is a {{Pro}} feature. In order to be able to access these advanced scripts, the [[GM]] of the campaign must be a [[Pro]] subscriber and enable it for their campaign.}}<br />
<br />
<br />
'''''How to Add the API Script to your Game'''''<br />
<br />
If you have a PRO account, you can install the API script by going to your game's Campaign Page and clicking on the '''Settings''' button, and then choosing '''API Scripts'''. This brings you to the API Scripts page for your current game. The Companion Script is part of the One-Click Community API Installation options. Under the Script Library tab, there is a drop down menu that lists all the available community created scripts. Scroll down till you find the '''System Toolbox''' category and select the "5th Edition OGL by Roll20 Companion" script. The version number, the script's author, and a brief description of what the script does will appear right below the drop down menu once it is selected. Below that, click on the blue "Add Script" button to add the script to your game.<br />
<br />
<br />
'''''List of API commands for the 5th Edition OGL Companion API Script'''''<br />
* <code>!5ehelp</code> - Gives a list of the script's API commands in the chat tab.<br />
* <code>!5estatus</code> - Lists the current status of the script's features in the chat tab.<br />
* <code>!ammotracking on/off/quiet</code> - Automatically expends linked resource when attack is made<br />
* <code>!autonpctoken on/off</code> - Automatically generates a NPC token on the GM's screen based on the default token when an NPC's health calculation is rolled<br />
* <code>!deathsavetracking on/off/quiet</code> - Automatically ticks off successes and failures when death saves are rolled, clearing on death, stabilization, or hp recovery<br />
* <code>!longrest <character name></code> - This will add Hit Dice recover and if spelltracking is on, this command will reset all of the character's spell slots to unspent.<br />
* <code>!npchp <character name></code> - Rolls NPC hit point totals using their formula and updates the token bar. If no character name is provided it will roll the selected tokens.<br />
* <code>!spelltracking on/off/quiet</code> - Automatically expends spell charges as cast, factoring in higher level casting, and spells marked as Rituals will not spend a spell slot.<br />
<br />
<br />
Options:<br />
* ''on'' - Toggles the functionality on (default)<br />
* ''off'' - Disables the functionality<br />
* ''quiet'' - Maintains functionality while preventing results from being output to the chat.<br />
<br />
<br />
===Automatic Ammunition Tracking===<br />
''Main Article:'' '''[[D&D 5E by Roll20: How to setup Ammunition and Resource tracker]]'''<br />
<br />
Automatic Ammunition Track is a feature that requires the above Companion API Script. Once installed, follow these instructions to enable automatic ammunition tracking in your game:<br />
<br />
This example sets up a Longbow with a quiver of Arrows to track.<br />
# On the Settings (Gear Icon) tab of a character sheet, under GENERAL OPTIONS, make sure that the INVENTORY option is set to "Compendium Compatible" and not "Simple".<br />
# While still under GENERAL OPTIONS, set the AMMO TRACKING feature to ON.<br />
# Create manually or drag a missile weapon (ex. Longbow) from the Compendium to your sheet.<br />
# Create manually or drag a missile type (Arrows) from the compendium to your sheet<br />
# Expand the missile type (Arrows) by clicking on the "I" information icon that appears when hovering the mouse over the item.<br />
# Select the USE AS RESOURCE checkbox. (ammunition items dragged from the Compendium will have this option automatically checked off)<br />
# On the CORE tab, expand the missile weapon (Long Bow) in the ATTACKS & SPELLCASTING section by clicking on the gear icon that appears when hovering over the attack.<br />
# In the AMMUNITION section put the exact name of the ammunition resource (Arrows). If you want to spend more than one piece of ammunition per shot you want to add the number of pieces after the name of the ammunition resource and a comma. (ex. ''Arrows,2'' )<br />
<br />
<br />
Now, any time the missile weapon (Longbow) is rolled, a piece of ammunition will automatically be spent and the chat will make note. Additionally after the first time the missile weapon is used the AMMUNITION section will update with the ID of the resource repeating section, this is normal and expected.<br />
<br />
<br />
===Automatic Spell Slot Tracking===<br />
<br />
Automatic Spell Slot Tracking is a feature that requires the above Companion API Script. Once installed, follow these instructions to enable automatic spell slot tracking in your game:<br />
* In the chat input area of the Sidebar, type ''!5estatus'' and press Enter, to check if spelltracking is set to 'on'.<br />
* If not, type ''!spelltracking on'' and press Enter to activate this feature.<br />
* Alternatively, you may type ''!spelltracking quiet'' and press Enter to activate this feature, while preventing spelltracking messages from being displayed in the chat.<br />
<br />
<br />
<br />
Once the Spell Slot Tracking has been activated, each time a spell is cast:<br />
# The number of cast spells of the appropriate level is updated in the Spell tab of the character sheet (see [[5th Edition OGL by Roll20|Spell Levels & Spells Per Day]]).<br />
# A message is output in the chat, displaying the spell level, the number of available spell slots and the number of used spell slots for this level.<br />
# Spell slots decrement as spells are cast. <br />
# Spells that are marked as a Ritual do not affect the tally of spell slots when cast.<br />
<br />
<br />
At any time, you can manually adjust this count directly in the Spell Page of the character sheet.<br />
<br />
=Updates=<br />
* {{hc|articles/360037772613-Change-Log Roll20 Changelog}} - Full Changelog of Roll20, updates for 5E sheet are included<br />
* {{fpl|10096810/ D&D 5th Edition by Roll20 (Q2Y2021)}} often has mentions of latest updates<br />
* Major Sheet Updates:<br />
** Feats can now be selected in Charactermancer {{fpl|8891809 June 2020}}<br />
** Game [[creator]] can select which [[compendiums]] are or aren't accessible in a game. [https://app.roll20.net/forum/post/8738570/release-note-for-may-26-2020 May 26 2020]<br />
<br />
=Known Issues=<br />
The sheet has a number of known bugs and issues, some which are mentioned in the sheet's latest forum thread.<br />
<br />
'''Charactermancer/Character Creation'''<br />
* '''Charactermancer & Compendium drag-n-drop doesn't work when sheet is in a separate window.''' This is [[Character_Sheets#Character_Sheet_in_a_separate_window|an inherit limitation to how character sheets work]] at the moment. <br />
* '''Multiclassing & spell selection''' - There are troubles when multiclassing spellcasters and getting to select spells from the right lists.<br />
* '''Duplicate races/classes from Essential Kit appear in selection''' You need to uncheck EK from your compendium for it to no longer appear in selections.<br />
<br />
<br />
'''General:'''<br />
* '''Warlock spell slots''' - The Warlock's spell slots don't work too well with the sheet, and most people use some manual adjustments for how they work. The number of spell slots also appears wrong in the Charactermancer.<br />
* '''NPC stat <code>desc</code> changed into <code>description</code>''' This was a recent update that broke some macros for people, resulting in error messages along: "can't find ''desc'' attribute" {{fpl|8297517/ release notes march 2020}}<br />
<br />
=Sheet Guides=<br />
* [[5E Macros]]<br />
* {{blog|638339117446578176/tome-of-tips-dungeons-dragons-5th-edition-ogl Tome Of Tips: The D&D 5E character sheet}}<br />
* {{yt.be|9BGGr97qJdY|Learning Roll20: EP01 Character Sheets (D&D 5E)}} 50min, by Roll20 (2020)<br />
<br />
=Related Pages=<br />
* D&D 5E by Roll20 sheet<br />
** [[D&D5E by Roll20 NPC Attributes]]<br />
** [[D&D 5e by Roll20 Roll Templates]]<br />
** [[D&D 5E by Roll20: How to setup Ammunition and Resource tracker]]<br />
* [[5E]] - general D&D 5E info for Roll20. Lists also the alterantive character sheets for 5E<br />
* [[D&D]] - Roll20 stuff on the various editions.<br />
* {{Compendium}}<br />
** [[Compendium Sharing]]<br />
* [[Character Vault]]<br />
<br />
=See Also=<br />
* {{repo|Roll20/roll20-character-sheets/tree/master/DD5thEditionLegacy Sheet sourcecode}} - (Public version of sheet code is 1½+ years behind from what is actually used)<br />
* {{hc|articles/360037772613-Change-Log Roll20 Changelog}} - Full Changelog of Roll20, updates for 5E sheet are included<br />
<br /><br />
<br /><br />
[[Category:Character Sheet Documentation]]<br />
[[Category:Official Sheet]]<br />
[[Category:DnD5E]]<br />
[[Category:Featured articles]]</div>5004103https://wiki.roll20.net/D%26D_5E_by_Roll20D&D 5E by Roll202021-10-01T16:27:18Z<p>5004103: /* Directly Referencing Attributes */</p>
<hr />
<div>{{revdate}}{{HCbox|{{hc|360037773573-5th-Edition-OGL-by-Roll20 D&D 5E by Roll20}} }}<br />
[[File:5E OGL Sheet Core v2.6.png|500px|thumb|right|The '''D&D 5E by Roll20''' Character Sheet]]<br />
<br />
This is the community-driven documentation for the '''[[5E|D&D 5E]] by Roll20''' character sheet. Previously the sheet was known as the '''"5th Edition OGL Sheet"''' or just the '''"OGL Sheet"'''.<br />
<br />
=The Basics=<br />
This page is a ''[[Community Wiki]]'' guide to the Official D&D 5th Edition character sheet, which is updated with info tricks that might not be covered by the {{hc|articles/360037773573-5th-Edition-OGL-by-Roll20 official sheet documentation}}.<br />
<br />
<br />
To find out about the latest updates, issues and talk about the sheet, check the {{fpl|10096810/ D&D 5th Edition by Roll20 (Q2Y2021)}}-thread on the {{forum|category/277980 forums}}.<br />
<br />
<br />
[[Bug|Bug reports]] for the sheet is best reported in the same thread. If you find bugs in the 5E Compendium or 5E marketplace content, {{bug}}.<br />
<br />
<br />
__TOC__<br />
<br />
==Adding the Character Sheet to a Game==<br />
[[File:D&D5E-Roll20-sheet-selection.png|300px|thumb|right|The Sheet Selection Menu]]An official or community contributed character sheet [[Add_character_sheet#Adding_a_Character_Sheet_to_your_Campaign|can be added to any game when you first create it]]. On the Game Creation screen, underneath the large blue '''“I’m Ready, Create Game!”''' button, is the '''“Optional: Choose a Character Sheet”''' section. Located here is a drop down menu that lists all the character sheets built either by Roll20 officially or created by the community. These sheets are sorted under their respective RPG Systems in alphanumerical order. Once selected, a preview of the character sheet will load upon the creation page for you to review as well as showcase relevant information about the sheet, such as the sheet’s creator and its key features.<br />
<br />
<br />
The '''D&D 5E by Roll20''' Sheet can be found under either: '''Sheets by Roll20''' → D&D 5E by Roll20 OR '''Dungeons and Dragons 5E''' → D&D 5E by Roll20<br />
<br />
<br />
If you want to add a character sheet to an existing campaign, you can find this drop down menu once again by accessing the [[Game Settings Page]] from the [[Game_Management#Game_Details_Page|Game Details]]-page.<br />
<br />
{{mbox | text = '''NOTE:''' If you have added custom attributes to your character journals prior to adding a character sheet to a campaign, you may want to delete them first. Adding a character sheet to a campaign will create its own set of custom attributes on all of your character journals, but it will reuse any attributes encountered if they share the same name. This can cause calculation issues on the sheet.}}<br />
<br />
<br />
If you were previously using either the [[DnD5e Shaped Character Sheet|D&D 5E (Shaped)]] or [[DnD5E_Community_Contributed|D&D 5E (Community Contributed)]] sheets and wish to transfer over to the '''D&D 5E by Roll20''' version, it's a good idea to ask help on the [https://app.roll20.net/forum/category/277980 forums].<br />
<br />
<div style="clear: both"></div><br />
<br />
==Where to Find the Sheet==<br />
Once a character sheet has been added to a game, and once inside it, on all [[Journal#Characters|Characters Journals]], a new tab will be available between the '''“Bio & Info”''' and '''“Attributes & Abilities”''' tab labelled '''“Character Sheet”'''. Much like the Attributes & Abilities tab, only players who have been granted Edit permissions for the journal entry will be able to access the Character Sheet tab.<br />
<br />
''See also:'' '''[[Add_character_sheet#Adding_New_Characters_In-Game|Create new character sheets to your players]]'''<br />
<br />
==Sheet Features==<br />
The '''D&D 5E by Roll20''' sheet has all of the functionality of a pen and paper character sheet, and much more. Certain aspects of the sheet have been streamlined or automated to remove bookkeeping and speed up gameplay. The key features are auto-calculations, [[Macro|macro]] buttons, and [[D&D 5e by Roll20 Roll Templates|roll templates]]. The sheet defaults to using the rules as printed in the D&D 5E SRD, however it's dynamic enough to allow you and your group to use many custom house rules you might want.<br />
<br />
===Auto Calculations===<br />
Many parts of the sheet use auto calculations to fill in derived attributes with the expectation that you're using the rules as printed in the 5th Edition SRD. Many of these calculated traits can be modified from the character sheet's <span style="font-family:Pictos;">y</span> [[D&D 5E by Roll20#Settings Page|Settings]]-tab, and those set by Sheet Workers can be edited directly. Below are some examples of Sheet Worker and Auto Calculation functionality:<br />
<br />
* '''Class''' - Changing the character's class from the header will automatically update the character's saving throw proficiencies, their hit die type, spell casting ability, and spell save DC. <br />
* '''Level''' - Changing the character's level will also update their proficiency bonus, number of spells per day, and more.<br />
* '''Attributes''' - Changing one of the character's attributes will also update the related modifier, skills that are based on that attribute, and derived stats such as initiative or passive perception.<br />
<br />
===Roll Buttons and Roll Templates===<br />
[[File:5E_OGL_Sheet_Rollable_Buttons.gif|right|frame|Any label that highlights in red when the mouse hovers over it is rollable.]]<br />
''Main Page:'' '''[[D&D 5e by Roll20 Roll Templates|D&D 5E by Roll20 Roll templates]]'''<br />
<br />
Most of the stats in the game can be rolled by hovering over their name, the stat will turn red, and then left-clicking the mouse. This is true for Attributes, Saves, Skills, Hit Dice, Death Saves, Tool Proficiencies, Attacks & Spellcasting, Spell Cards, and NPC Actions/Attacks. Any of these roll buttons can be dragged directly from the sheet to your [[Macro Quick Bar]], enabled from the <span style="font-family:Pictos;">y</span> [[My Settings]]-tab of Roll20's [[Sidebar]].<br />
<br />
Player characters have both a simple and attack [[D&D 5e by Roll20 Roll Templates|roll template]] that is output to the {{Text Chat}}-tab on the right hand [[Sidebar]]. The simple template is used for everything except for attacks. The attack template is shaped to show up in three pieces; the attack at the top, information in the middle, and damage at the bottom. Depending on your sheet settings, the damage will not roll automatically unless you click on the name of the attack from the roll template in the chat tab. This was designed to simulate the tabletop experience of rolling to attack and then rolling damage if necessary. You can change this behavior in the sheet <span style="font-family:Pictos;">y</span> [[D&D 5E by Roll20#Settings Page|Settings]]-tab, tab under "Auto Damage Roll".<br />
<br />
<div style="clear: both"></div><br />
<br />
====Rolling for Advantage and Disadvantage====<br />
With the '''D&D 5E by Roll20''' Sheet, the [[D&D 5E by Roll20#Settings Page|default sheet settings]] has Advantage set to ''always'' rolled for convenience purposes. It is commonly agreed upon that a gaming group uses the left roll result when advantage is not being used for a check. When advantage or disadvantage is in play, simply choose the higher or lower result among the two per usual. You can change this behavior in the sheet <span style="font-family:Pictos;">y</span> [[D&D 5E by Roll20#Settings Page|Settings]]-tab (gear icon at the top right of the page), tab under "Roll Queries". You have the choice of "Always Roll Advantage" (the default setting), "Advantage Toggle", "Query Advantage", or "Never Roll Advantage".<br />
<br />
'''Advantage Toggle:''' The Advantage Toggle will add three buttons to the top of your character sheet: "Advantage", "Normal", and "Disadvantage". You can click on any of these to roll for Advantage (the highest roll result will highlight in black), Disadvantage (the lowest roll result will highlight in black), or a single d20.<br />
<br />
'''Query Advantage:''' The Query Advantage setting will prompt a dialog box to appear whenever you roll from your sheet. It will ask you to select what sort of roll want to do (Normal, Advantage, Disadvantage). After choosing the type you want, the roll will occur in chat.<br />
<br />
'''Never Roll Advantage:''' When rolling from your sheet, only a single d20 will be rolled.<br />
<br />
===Resizable Text Fields===<br />
[[File:5E_OGL_Sheet_Resizable_Text_Fields.gif|right|frame|Making a text field larger is just a matter of click and dragging.]]There are many free-text fields on the sheet that give you a place to keep information that doesn't necessarily follow a specific format. All of the fields on the Bio Tab are free-text fields as well as the Description fields present for attacks, spells, equipment, features & traits, and NPC actions. If your text overflows past the bottom of a text field, you can resize it to view the content in its entirety by clicking and dragging the bottom right corner icon shown in the adjoining image.<br />
<br />
<br />
At present, these fields can only contain raw text. There are no formatting options (bold, italic, etc.) available.<br />
<br />
<div style="clear: both"></div><br />
<br />
===The Padlock Button and Organizing Elements===<br />
(aka. '''[[Character_Sheets#Repeating_Section|Repeating Section]]''')<br />
[[File:5E_OGL_Sheet_Padlock.gif|right|frame|The Padlock Toggle]]There is a <span style="font-family:Pictos;">(</span> (padlock) icon set at the bottom of several different fields of the '''D&D 5E by Roll20''' Sheet. It is used where a player is meant to add entries such as individual attacks, actions, pieces of equipment, features & traits, tool proficiences & custom skills, other proficiencies & languages, and spells. This icon behaves as a toggle button. <br />
<br />
When set in the <span style="font-family:Pictos;">(</span> locked position (default), a player can add new entries into the field. When the button is toggled to <span style="font-family:Pictos;">)</span>(unlocked), a player can no longer add new entries, but they will be able to reorder or delete any of the existing ones. The <span style="font-family:Pictos;">#</span>(red trash bin)-icon overlaid on the right hand side of the entry will delete it.<br />
<br />
{{Ambox<br />
|nocat=true<br />
| type = content<br />
| text = '''Deleting an entry cannot be undone!''' On left side of every entry while the padlock is <span style="font-family:Pictos;">)</span> unlocked is a re-sort icon symbolized by '''<big>≡</big>'''(three parallel lines). By clicking and dragging on this icon, you can rearrange the order of the entries in the field.<br />
}}<br />
<br />
{{Ambox<br />
|nocat=true<br />
| type = content<br />
| text = Some of the features of '''Repeating Sections''' do not work when the [[Character_Sheets#Character_Sheet_in_a_separate_window|Character Sheet is in a separate window]].<br />
}}<br />
<br />
<br />
<div style="clear: both"></div><br />
<br />
==Utilizing the 5th Edition SRD Compendium==<br />
[[File:5E_OGL_Sheet_Compendium.png|right|The Compendium Tab]]Upon adding the D&D 5E by Roll20 Character Sheet to a campaign, the [https://app.roll20.net/compendium/dnd5e/BookIndex| 5th Edition SRD Compendium] is automatically enabled for use from it's own <span style="font-family:Pictos;">i</span> [[Compendium]]-tab in the '''[[Sidebar]]''' of the application. It's located between the {{Journal}} and <span style="font-family:Pictos Custom;">u</span> [[Jukebox]]-tabs, and is accessible for both GM and Player alike.<br />
<br />
<br />
The <span style="font-family:Pictos;">i</span> [[Compendium]] allows for rapid searching of all rules, classes, monsters, spells, items, and more that are included in the 5th Edition SRD. This minimizes time spent for the gaming group to leaf through a book in the middle of a session for a rule clarification. Even better, both the GM and the Player can utilize dragging and dropping* from the <span style="font-family:Pictos;">i</span> [[Compendium]]-tab directly to your character sheets. This makes statting NPCs and PCs far faster than inputing everything manually.<br />
<br />
{{mbox | text = '''NOTE:''' The 5th Edition SRD is similar but NOT identical to the ''Dungeons and Dragons'' 5th Edition Rule Book. Some skills, classes, creatures, items, and other elements found within the ''Dungeons and Dragons'' rule book are strictly intellectual property of Wizards of the Coast and not accessible through their Open-Game License(OGL).}}<br />
<br />
<br />
===Statting PCs===<br />
Dragging from the <span style="font-family:Pictos;">i</span> [[Compendium]] works for the Equipment and Spell fields of the PC Sheet. This will not only carry over the name of the item or spell, but the relevant attack and damage rolls and any rules or flavor text that comes with it. Adding Compendium items in this fashion also automatically adds the equipment item (if it's a weapon) or spell to the Attacks & Spellcasting field to roll directly from. Items that modify a character's Attributes, Saves, AC, To Hit, Damage, Spell Attacks, and Spell DC will be automatically calculated on the sheet when dragged in. For example, if a Belt of Giant Strength is dragged to a sheet, the strength Attribute Score will become highlighted in blue and its attribute score will be increased. An asterisk is appended to the right of the score to also signify that it has been modified by an item. When you mouse over this number, the strength Attribute Score will revert back to what its unmodified total so you can refer back to it. Dropping a Compendium items that is an ammunition type (arrows, crossbow bolts, blowgun darts, etc) will automatically fill out a resource field for that item and link it to its entry in the Equipment section.<br />
<br />
To insert a Compendium item into the character sheet, run a search for the Item or Spell you want to add in the <span style="font-family:Pictos;">i</span> [[Compendium]]-tab. Once found, click and drag on the Compendium item's name so that it creates a little named tile that follows along with your mouse. Drag this over to the character sheet, it doesn't matter where. A text box that reads, "ACCEPTING DROP FROM COMPENDIUM" will appear on your sheet if this is done correctly. Let go of the tile and the entry will be auto-completed with all the data pertaining to the the Compendium entry in the correct location on the sheet. You can see this in action below under [[#Equipment|Equipment]].<br />
<br />
===Statting NPCs===<br />
You can fill out an entire NPC sheet in a single drag and drop. Run a search for the NPC you want to create from the <span style="font-family:Pictos;">i</span> [[Compendium]]-tab. Once found, click and drag on the NPC name so that it creates a little named tile that follows along with your mouse. Drag this to anywhere over the Tabletop area of the screen. Let go of the tile and a new character journal will be created named after the NPC from the Compendium entry. Its sheet will be changed over to the NPC sheet and filled with the entire NPC entry from the Compendium including their Actions, Reactions, and Legendary Actions if applicable. If you're using one of the Compendium expansions bought from the Roll20 Marketplace like the Monster Manual or Volo's Guide to Monsters, token art will also be pulled from the Compendium entry, placed on the table, and linked to your NPC's journal.<br />
<br />
You can also drag an NPC entry from the Compendium to an existing journal entry if you have the sheet open. If the sheet is in PC sheet mode, it will automatically change it over to the NPC sheet, and add its entry elements to it.<br />
<br />
One thing to note about dragging a stat block over from the Compendium is that it uses an ''additive'' behavior. It will not replace anything that you have already entered manually.<br />
<br />
=The PC Sheet=<br />
The '''D&D 5E by Roll20 Sheet''' contains both the PC Sheet ''and'' the NPC Sheet. By default, a new character journal is set to the PC sheet, but you can switch between the two by toggling it from the [[#Settings Page|General Options Settings]]. The PC Sheet is split up into four pages and can be selected from the buttons just underneath the header at the top of the sheet. They are listed from left to right order: The [[#Core Page|Core Page]], The [[#Bio Page|Bio Page]], The [[#Spells Page|Spells Page]], and The [[#Setting Page|Setting Page]].<br />
<br />
== Creating and Leveling up a character with Charactermancer ==<br />
Players and GMs using the '''D&D 5E by Roll20''' Sheet can use the Charactermancer to create and level up characters.<br />
<br />
'''How to use the Charactermancer for [[Charactermancer (D&D Fifth Edition)|character creation and leveling]].'''<br />
<br />
<br />
{{Ambox<br />
|nocat=true<br />
| type = content<br />
| text = The Charactermancer do not work when the [[Character_Sheets#Character_Sheet_in_a_separate_window|Character Sheet is in a separate window]].<br />
}}<br />
<br />
==Core Page==<br />
[[File:5E_OGL_PC_Core_Guide.jpg|right|frame|The Core Page]]The Core Page is selected by default and has most of the information you'll want to use on a regular basis to play your character. This should look very similar to the content you would normally find on the first sheet of the physical "D&D 5E by Roll20" player character sheet. The screenshot at the top of this wiki page displays the entirety of the Core Page. <br />
===(1) Core Header===<br />
[[File:D&D5E-Roll20-core-header.png|550px]]<br />
<br />
The header block at the top of the sheet changes based on the page you have selected. On the Core page you can select a class by its dropdown menu. The available options from the dropdown are: Barbarian, Bard, Cleric, Druid, Fighter, Monk, Paladin, Ranger, Rogue, Sorcerer, Warlock, and Wizard. You can create a custom class from the Settings Page.<br />
<br />
Once a class has been selected you can update the class's level by changing the number next to the class. The sheet will also automatically mark the abilities that class has proficiency in as well as automatically select the dice that will be used when Hit Dice are rolled. You can change the Hit Dice setting manually from the options menu. If your character multi-classes, then the secondary class and its level will appear beside the primary class. This Class and Level field can hold up to four classes if desired.<br />
<br />
The fields for Background, Race, Alignment, and Experience Points allow you to fill in whatever text you wish to put in them. The Character Name persists over all pages of the sheet and is tied to the name you give to the journal entry. Changing it on the sheet itself will also change the name on the character journal and vice versa once it is closed.<br />
<br />
===(2) Attributes===<br />
<br />
[[File:5E_OGL_Sheet_Attribute_Block.jpg|left]]Along the left side of the sheet are listed the 6 primary attributes: Strength, Dexterity, Constitution, Intelligence, Wisdom, and Charisma. These attributes are used by almost every other calculation on the sheet, as they are the core definition of a character. Each attribute block has the core attribute score, which can be changed by modifying the number in the oval at the bottom of each block, and, inside the square, the attribute modifier which is auto-calculated based on the score below it. All racial ability score increases must be manually added to the core attribute score using the settings "gear" symbol at the top of the page (where the Core, Bio, and Spells buttons are located.) The attribute modifier uses the following calculation to set the value:<br />
<br />
<br />
<code>[[floor((@{strength}-10)/2)]]</code><br />
<br />
The attribute can be referenced by its name, such as @{dexterity} while the attributes modifier can be referenced by adding the mod suffix, @{dexterity_mod}.<br />
<br />
<div style="clear: both"></div><br />
<br />
===(3) Inspiration===<br />
<br />
[[File:D&D5E-Roll20-inspiration.png|left]]You can track whether or not you have Inspiration by clicking the circle next to the Inspiration block at the top left of the Core page. This will toggle a dragon spiral icon on and off for indication purposes.<br />
<br />
<div style="clear: both"></div><br />
<br />
===(4) Proficiency Bonus===<br />
<br />
[[File:5E_OGL_Sheet_Proficiency.png|left]]Your character's proficiency bonus is listed near the top left of the page. You cannot modify this value manually, instead it is automatically set based off your character's over-all level. Your character's Level can be set by changing the number next to your Class name in the [[#header_info|Header]] at the top when on the Core page.<br />
<br />
<div style="clear: both"></div><br />
<br />
===(5) Saving Throws===<br />
<br />
[[File:5E_OGL_Sheet_Saving_Throws.png|left]]Next to the core Attributes on the left side of the page is a list of the same attributes to be used in making saving throws. To mark an attribute that your character has proficiency in for saving throws, check the box next to the appropriate attributes. When you select a class in the header section of the Core page it will automatically check the correct boxes for that class's proficiencies.<br />
<br />
You can add an additional field to Saving Throws to serve as a Global Save Modifier. An example is if the character is under the influence of the Bless spell and can roll a 1d4 in addition to the result of their saving throws. This is enabled from the Settings Page under General Options. Once enabled a seventh checkbox and field will be added at the bottom of the Saving Throws block with a text field to enter the additional die roll. For this example, you could enter "1d4[BLESS]" in the global checkbox's text field that you can enable when the character is under the effects of the Bless spell. The word between the brackets becomes a label that can be seen when you mouse over the roll result in chat. While this Global Save Modifier is checked, every roll made from the Saving Throws block and performing a Death Save will add this modifier to the result.<br />
<br />
<div style="clear: both"></div><br />
<br />
===(6) Skills===<br />
[[File:5E_OGL_Sheet_Skills.png|left]]<br />
To the right of the Core Attributes is a list of all of the character's Skills. Each skill can be rolled by clicking on the skill name. If you have proficiency in a specific skill, then you would check the box next to the skill name, this will automatically add your proficiency bonus to that skill's checks. Each skill also lists the core attribute, that is used in the roll calculations, next to it in parenthesis.<br />
<br />
You can set advanced skill options for the Settings page, such as skill expertise, flat bonuses from class archetypes or feats, as well as Jack of All Trades.<br />
<br />
<div style="clear: both"></div><br />
<br />
===(7) Armor Class, Initiative, & Speed===<br />
<br />
[[File:D&D5E-Roll20-AC-Init-Speed.png|left]]The Armor Class & Speed blocks at the top center of the page can be used to keep track of your Armor and Speed values. The Initiative block cannot be modified manually, but instead is auto-calculated based off your character's Dexterity. If you have any additional initiative modifiers you can add them on the {{gear}} [[#Settings Page|Settings Page]] under Initiative Modifier in the Class Options block.<br />
<br />
Armor Class can also be tracked automatically by using the [https://app.roll20.net/compendium/dnd5e/BookIndex Compendium] compatible inventory, on by default.<br />
<br />
You can configure a custom AC calculation using the {{gear}} [[#Settings Page|Settings Page]] under the Attribute Tracking section. It's listed as "Armor Class Tracking" and is set to "Automatic" by default. If you select Custom, you can select up to two different attributes to apply to the character's armor class.<br />
<div style="clear: both"></div><br />
<br />
====Using the Global AC Modifiers====<br />
If you check the "Show Global AC Modifier" field in the character sheet General Options settings, the sheet will display a repeating section to configure and apply different modifiers to AC. So, for example, if your character has a common bonus, such as from a spell or a conditional feat or fighting style, you can toggle that AC bonus from the character sheet directly.<br />
<br />
====Rolling for Initiative and the Turn Order Tracker====<br />
Clicking on the word INITIATIVE will roll that character's initiative score. If your players have [[Token|tokens]] linked to their character sheets, they can roll their initiative ''and'' simultaneously add their character and its initiative score to the {{Turn Tracker}} automatically. What is required of the player is that their linked token must be currently selected on the Tabletop before they roll off their sheet.<br />
<br />
If you would like to enable a tie breaker component to Initiative, there is an option to enable this from the [[#Settings Page|Settings Page]] under the "Attribute Options" block. What this does is that it will add your dexterity Attribute Score as a decimal value to your Initiative. So if you have a character with a dexterity attribute score of 14, your initiative modifier will change from a <code>2</code> to a <code>2.14</code>.<br />
<br />
===(8) Hit Points & Temporary Hit Points===<br />
[[File:5E_OGL_Sheet_HP.png|left]]The Current Hit Points and Temporary Hit Points blocks are used to keep track of your character's Hit Points (HP). Inside the Current Hit Points block, at the top, is a line that lists the character's maximum amount of HP. <br />
<br />
<br />
When your character takes damage, if they have any, it should be subtracted from their Temporary Hit Points first, then any remaining damage would then come off of the character's Current Hit Points.<br />
<br />
<div style="clear: both"></div><br />
<br />
===(9) Hit Dice===<br />
[[File:5E_OGL_Sheet_Hit_Dice2.png|left]] The Hit Dice block is used to keep track of and roll your character's hit dice. Inside the Hit Dice block, at the top, is a line to keep track of the total number of dice your character can have. In the main area of the block you would keep track of the remaining hit dice. Clicking the "HIT DICE" label will roll the hit dice for your selected class automatically. If you wish to change the dice that is rolled you can do so in the Class Options section of the [[#Settings Page|Settings Page]] ({{gear}} icon). <br />
<br />
<br />
If your character is multi-classed, when rolling your hit dice (by clicking "''HIT DICE''", a pop-up will ask which of your character's current class's hit dice you want to roll. This input accepts only numerals a input to make automatic tracking of the [[API:A Guide to the API|API]] possible.<br />
<div style="clear: both"></div><br />
<br />
===(10) Death Saves===<br />
[[File:5E_OGL_Sheet_Death_Saves.png|left]]The Death Saves block is used to keep track of your character's death save rolls once they have been knocked out. You can click the "DEATH SAVES" label to make a death save roll. If you roll greater than 10 you would check one of the boxes next to "Successes" otherwise you would check a box next to "Failures". If your character has any modifiers to their death save rolls they can be added in the Class Options section of the Settings Page(gear icon).<br />
<div style="clear: both"></div><br />
<br />
===(11) Attacks & Spellcasting===<br />
[[File:5E_OGL_Sheet_Attacks_And_Spellcasting.png|left]]The Attacks & Spellcasting block in the center of the Core page of this character sheet will be one of the most often used sections. To start, you can manually add any attack or spell to this section by hovering over the block and clicking the "Add" button(the <span style="font-family:Pictos;">&</span> symbol). This will open a form that can be filled out with all of the information about the specific attack or spell you are adding. <br />
<br />
<br />
This section will automatically add attacks, with all the stats, for spells that have an attack component when they are added to your spell sheet on the [[#Spells Page|Spells Page]]. This happen both if you add the spell manually or if you drag and drop a spell from the <span style="font-family:Pictos;">i</span> [[Compendium]]. An attack is also automatically created if you drag and drop an item from the Compendium into your sheet.<br />
<br />
<div style="clear: both"></div><br />
[[File:Poisoned Dagger 5e Attack.png|right|frame|An example of an attack form filled out for a physical attack using a +1 Poisoned Dagger]]For example, lets say Erin the Bold has a +1 Poisoned Dagger that has the stats of a regular dagger, but also metes out an additional 1d6 of poison damage alongside the typical 1d4 points of piercing damage. The image displayed to the right is how the attack would be set up:<br />
<br />
<br />
Since this is a [https://app.roll20.net/compendium/dnd5e/Items:Dagger#h-Dagger dagger], and daggers have the "[https://app.roll20.net/compendium/dnd5e/Weapons#h-Weapons Finesse]" attribute I can chose either STR or DEX for my bonus attribute. Erin is quicker than she is strong, so we will pick DEX as the attribute to attack with, as well as checking the "proficient" checkbox since Erin is experienced with using these sorts of weapons. She doesn't have any other gear that might make her attacks better, so we will leave the generic bonus between the attribute and proficiency blank, or 0. Being a +1 Poisoned Dagger means that it is also magical, so it gets a 1 in the magic bonus slot just below. A dagger can also be used as a thrown weapon, so we've added the weapon's throwing range info to the "Range" field. Since a weapon does damage, we have checked the first "Damage" checkbox and filled in the required fields. This dagger does 1d4 piercing damage + Erin's DEX mod + 0 bonus damage (this would be used for bonus damage on top of the magical +1) and it doesn't have anything to change the critical damage so we just put the same damage into the "crit" box. Because this dagger can also cause poison damage, we also check the second "Damage" checkbox and fill in the info for the 2nd set of damage. The poison does a flat 1d6 poison with no extra bonuses, so we've selected "-" to say there is no attribute that adds to this damage. This damage also doesn't have anything to make the crit different so we set that to 1d6 as well. There are no extra saving throws or effects that are included with this attack, so we leave these additional sections blank. <br />
<br />
These additional effect sections will be used more commonly with spells, like [https://app.roll20.net/compendium/dnd5e/Fireball#h-Fireball Fireball], where you would require a DEX save against your SPELL DC, which will be set according to your character's spell casting level. For a fireball, the save effect would be "half damage" and the "Description" would be something like "Hits all creatures within 20 ft of the explosion point".<br />
<br />
After you are done modifying all of individual stats for an attack you can click the gear icon at the top right of that section and it will hide the stats for that attack. If ever you need to change these stats in the future you can hover over the entry and click the <span style="font-family:Pictos;">y</span>(gear)-icon that shows up to unhide the stats section. <br />
<br />
<div style="clear: both"></div><br />
====Adding Global Attack and Damage Modifier====<br />
You can add two special entries to the Attacks & Spellcasting block to handle to global Attacks and Damage modifications to rolls. An example is if the character is under the influence of the Bless spell and can roll a 1d4 in addition to the result of their attack roll. This is enabled from the [[#Settings Page|Settings Page]] under General Options. Once enabled, a checkbox will be added at the bottom of the Attacks & Spellcasting block with a text field to enter the additional die roll. For this example, you could enter <nowiki>"1d4[BLESS]"</nowiki> in the global checkbox's text field that you can enable when the character is under the effects of the Bless spell. The word between the brackets becomes a label that can be seen when you mouse over the roll result in chat. While these Global Modifiers are checked, every roll made from the Attacks & Spellcasting block will add these modifiers to the result.<br />
<br />
====Rolling from the Attacks & Spellcasting Block====<br />
[[File:Poisoned Dagger 5e Roll.png|frame|An attack roll from a +1 Poisoned Dagger]]Rolling from the Attacks & Spellcasting Block is no different than rolling from any other portions of the character sheet. Hovering your mouse over any entry here will highlight its entire label (NAME, ATK, and DAMAGE/TYPE) in red and you'll be able to click on it to roll the attack or spell. You can also drag this entry into the Macro Bar to give yourself easy access to this attack. Because this is a repeating section, the macro name will be a bit messy, but you can right-click the button and rename the macro to whatever you like.<br />
<br />
With any attack that checks for AC, you will see TWO rolls set side by side for the Armor Class check with the name of the attack listed underneath them with the Attack modifier bonus (ATK) appended to the Attack name in light grey. The Roll20 D&D 5E Character Sheet ''always'' rolls for Advantage by default, so you will always have two roll results for this check (most gaming groups use the left roll result if neither Advantage or Disadvantage is being factored in the check). If there is a specified range for the attack, this will be listed above the attack's name.<br />
<br />
Underneath the AC Check and Attack Name is the Damage roll result for the attack. Underneath this roll result will be the Damage Type (ex. slashing, piercing, poison, fire, etc.) listed in light grey italicized font.<br />
<br />
For spells that don't check for AC and instead require a Saving Throws to mitigate or negate the spell's effect, the SPELL DC is listed first. Underneath this, in italicized font, is the effect if a character succeeds the check listed. Underneath the effect is the required attribute saving throw that must be rolled. If Damage is applied, this result is rolled and listed next with its Damage Type.<br />
<br />
[[File:5e_attack_example.gif|right|frame|How to view attack damage when the sheet is set to "Don't Auto Roll Damage"]]<br /><br />
<br />
<br />
{{mbox | text = '''NOTE:''' If your character sheet's Settings have "Auto Damage Roll" set to "Don't Auto Roll Damage" under General Options, the damage will not be listed underneath the AC roll result in chat. The damage was rolled, but presently hidden from view. Anyone can see the damage delivered by manually unfolding the roll result open by hovering your mouse over the roll result in chat and clicking on the attack/spell's name.}}<br />
<div style="clear: both"></div><br />
<br />
===(12) Personality Traits, Ideals, Bonds, and Flaws===<br />
These text fields lock to prevent accidental edits. When a sheet is first created, these fields are unlocked and given a dashed yellow border to the top of the field to showcase that they're editable. To lock the field after entering text, click on the gear icon in the upper right corner of the field. This will remove the yellow border and the field will conform in height to display everything within it.<br />
<br />
There presently isn't a means to format the raw text (italicize, bold, font alignment, etc) within these fields and any line breaks are stripped out. If you ever need to edit the content again while the field is locked, mouse over the desired field and the gear icon will reappear in the top right. Clicking on that will unlock the field once again for edits.<br />
<br />
===(13) Class & Other Resources===<br />
[[File:5E_OGL_Sheet_Resources.png]]<br />
<br />
The Class & Other Resource Blocks can be used to keep track of either an item quantity you have in your equipment (like arrows in a quiver), or skills that don't fit into the other sections on the sheet (like a '''Sorcerer's Sorcery Points''', a '''Cleric's Channel Divinity''' at higher levels, or the number of rounds a '''Barbarian''' has been '''Raging''' so far in a combat encounter).<br />
<br />
There are 3 fields per Block:<br />
* Resource Max:<br />
** The Resource Max field is a text box which allows you to quantify exactly what you're tracking (ex. "Total: 10 Rounds").<br />
* Resource:<br />
** The Resource field is a numeral that you dial up or down or input directly.<br />
* Resource Name:<br />
** The Resource Name is a text box that allows you to label the resource when you click on the light grey "OTHER RESOURCE" label to overwrite it with your own.<br />
**"OTHER RESOURCE" is placeholder text<br />
<br />
<br />
A resource block will be filled automatically if you checkmark an Equipment item as "USE AS A RESOURCE" & the Item Quantity field will be paired with the Resource field in the Resource block & vice versa (you'll need to click outside of the field or hit Enter for changes to refresh across the sheet). If the two resource blocks given by default are not enough then you can add additional blocks by hovering over the section & clicking the "Add" (+ symbol) button.<br />
<br />
The Item Name will also be added to the Resource Name field, however the Resource Max field is apparently not linked to the Item currently.<br />
<br />
If you drag & drop an ammunition item type from the Compendium into your character sheet, the item is added to the Equipment block & is automatically listed & linked as an Other Resource.<br />
<div style="clear: both"></div><br />
To call the first set of class resources use:<br />
* Class Resource <code>@{class_resource}</code><br />
* Other Resource <code>@{other_resource}</code><br />
<br />
<br />
To call the Repeating resources use<br />
* Repeating Resource 1st left<code>@{repeating_resource_$0_resource_left}</code><br />
* Repeating Resource 1st right<code>@{repeating_resource_$0_resource_right}</code><br />
* Repeating Resource 2nd left<code>@{repeating_resource_$1_resource_left}</code><br />
* Repeating Resource 2nd right<code>@{repeating_resource_$1_resource_right}</code><br />
* etc.<br />
<br />
<br />
If you want to do a basic Full Readout of the Repeating Resource, the Format would be (Top Left to Bottom Right):<br />
* Class: <code>@{class_resource_name}: @{class_resource} / @{class_resource|max}</code><br />
* Other: <code>@{other_resource_name}: @{other_resource} / @{other_resource|max}</code><br />
* Left 0: <code>@{repeating_resource_$0_resource_left_name}: @{repeating_resource_$0_resource_left} / @{repeating_resource_$0_resource_left|max}</code><br />
* Right 0: <code>@{repeating_resource_$0_resource_right_name}: @{repeating_resource_$0_resource_right} / @{repeating_resource_$0_resource_right|max}</code><br />
* Left 1: <code>@{repeating_resource_$1_resource_left_name}: @{repeating_resource_$1_resource_left} / @{repeating_resource_$1_resource_left|max}</code><br />
* Right 1: <code>@{repeating_resource_$1_resource_right_name}: @{repeating_resource_$1_resource_right} / @{repeating_resource_$1_resource_right|max}</code><br />
* etc.<br />
<br />
===(14) Tool Proficiencies===<br />
[[File:5E_OGL_Sheet_Tool_Proficiencies.png|left]]The Tool Proficiencies block is for listing a character's Tool Proficiency skills. At the bottom of this block is an "Add" (<span style="font-family:Pictos;">&</span> symbol) button. Clicking this will add a new entry to this block where you can add all of the relative stats for a specific tool proficiency, say Woodcarver's Tools. You can set the level of proficiency to either Proficient, Expertise, or Jack of All Trades. The roll bonus for that tool will reflect the proficiency level selected. Next is an Attribute drop down menu where you can select which character attribute to roll with for a proficiency check. One of the options you can choose is "QUERY ATTRIBUTE" which when you click on the Tool Proficiency to roll it, you will be prompted to choose which attribute you would like to use. The attribute used for the check will be up to the GM when it is time to make the roll check. If there is any additional bonus modifiers that come along with the tool in question, you can input it in the "MODS:" field.<br />
<br />
Once you finished filling out the stats for this tool you can click the <span style="font-family:Pictos;">y</span>(gear) icon at the top right of the entry to hide the stat fields and leaving behind just the rollable button. You can roll by either clicking on this rollable button or dragging it to your [[Macro Bar]].<br />
<br />
You can also use this section to create custom skills or rolls for your campaign setting or home-brew ruleset. Check out the [[#Custom Skills and Stats|Advanced Use]] section for further details.<br />
<br />
====Global Skill Modifier====<br />
You can add a special entry to the Tool Proficiencies & Custom Skills block to handle to global Attacks and Damage modifications to rolls. An example is if the character is under the influence of the Guidance spell and can roll a 1d4 in addition to the result of their skill check. This feature is enabled from the [[#Settings Page|Settings Page]] under General Options. Once enabled, a checkbox will be added at the bottom of the Tool Proficiences & Custom Skills block with a text field to enter the additional die roll.<br />
<br />
For this example, you could enter "1d4[Guidance]" in the global checkbox's text field that you can enable when the character is under the effects of the Guidance spell. The word between the brackets becomes a label that can be seen when you mouse over the roll result in chat. While this Global Modifier is checked, every roll made from the Tool Proficiencies & Custom Skills block and the Skills block will add this modifier to the result.<br />
<div style="clear: both"></div><br />
<br />
===(15) Other Proficiencies & Languages===<br />
[[File:5E OGL Sheet Proficiencies.png|left]]<br />
This block can be set up to be Compendium Compatible (where you can add repeating sections for individual items) or as one resizable free-text field to enter whatever you wish in here. If you don't feel the Tool Proficiency block is needed (as in, you don't feel like your party will ever have to roll individual tool sets), you can store a character's Tool Proficiencies here instead. There presently isn't a means to format the raw text (italicize, bold, font alignment, etc). You can adjust this block's behavior by going to the Settings Page of the sheet and going to the General Options block to change whether this block uses the Simple or Compendium Compatible layout.<br />
<br />
When the Other Proficiences & Languages block is made Compendium Compatible, each repeating field lists a Type selection field and a Proficiency text field. Type has the following options available from its drop down selection menu: Language, Weapon, Armor, Other. <br />
<p style="clear:both;"></p><br />
<br />
===(16) Equipment===<br />
[[File:5E OGL Sheet Equipment.png|framed|right|The Equipment block of the PC Sheet]]<br />
The Equipment block at the bottom of the page has 2 different versions: a Simple version that features a single plain text field where you can track all of your equipment in any format you wish and a Compendium Compatible version that allows you to drag and drop items from the Compendium to automatically populate repeated sections for each indivdual piece of equipment.<br />
<br />
To swap between the two different Equipment block versions, first, go to the sheet's Settings Page (gear icon at the top right of the page) and then to the "General Options" section. Here, on the field labeled "Inventory", you can select between "Simple" or "Compendium Compatible" respectively. Like the name implies, if you want to be able to copy items directly from the Compendium using drag and drop, you must use the Compendium Compatible version. Dragging item entries from the Compendium to the character sheet will add it fully filled in the Equipment section as well as other automated actions described below.<br />
<br />
====Automated Compendium Functionality====<br />
If you populate the Equipment block by dragging and dropping <span style="font-family:Pictos;">i</span> [[Compendium]] items, there are several automatic features that occur when the entries you drag in our equipment items.<br />
Auto-Equip: Every item dragged to the sheet is automatically equipped in the Equipment Section<br />
*'''Weapons:''' A weapon dragged in from the Compendium will add an attack in the Attacks and Spellcasting section for that item.<br />
*'''Armor:''' Armor that is dragged in from the Compendium will add its bonus to the Armor Class (while equipped) section. If you drag multiple pieces of armor to the same sheet and at least two armor entries are equipped at once, a warning will pop up in red at the top of the Equipment Block that the Armor Class isn't being correctly calculated because of the bonus overlap. This warning will dissapear when you unequip down to a single set of armor.<br />
*'''Magical/Wondrous Items:''' Items that modify Attributes, Saves, AC, To Hit, Damage, Spell Attacks, and Spell DC will add that bonus to those elements on the sheet. In most cases, the attribute that is being modified will highlight in blue and followed with an asterisk to showcase that the attribute is being modified by an item. Mousing over the modified number will display the base value of that attribute before the item's modification is applied. This stat modification only applies if the item is equipped in the Equipment section and it will remove its bonus if it is unequipped.<br />
*'''Ammunition:''' Items dragged in from the Compendium that are used for ammunition such as arrows, bolts, darts, and slingstones, will automatically populate and link to an Other Resource field.<br />
<br />
====Manually Adding Items====<br />
You can also add items manually by hovering over the block and clicking the "Add" button (+ symbol). Each equipment entry, by default, show fields for quantity, name, and weight of an item. If you hover over a row and click the small "information" icon (grey-filled circle with a lowercase i centered in it) that appears at the bottom right of the entry you can also set some additional features. <br />
<br />
*'''Equipped Checkbox:''' The checkbox changes the appearance of the Item Name so it's easier to tell what your character currently has equipped from a glance. When left unchecked, the Item Name's font turns grey. When checked, the Item Name becomes a solid black.<br />
*Use As A Resource Checkbox: When checked, this will enable one of the Class Resource blocks and list the item name and its quantity within it. The quantity is tied between the two so changing it in one will be reflected in the other field after clicking outside the field.<br />
*'''PROP:''' This is a text field where you would take note of weapon properties such as ''finesse'', ''versatile'', or ''light''.<br />
*'''MODS:''' This is a text field where you would take note if an item (likely magical) would modify your stats in some fashion such as a character's Attributes, Saves, Skills, AC, To Hit, Damage, Spell Attacks, and Spell DC. If a stat is modified here, its attribute value will become highlighted in blue and adjusted by the supplied modifier listed here. An asterisk is appended to the right of the value to also signify that it has been modified by an item. While your mouse is hovering over the attribute, it will revert back to its unmodified total so you can refer back to its pre-moddified value.<br />
**The format for a stat modification is ''stat name:n'' where n is the stat bonus (ex. ''Strength:21'')<br />
*'''Description Field:''' This is a simple text field to include a description of the particular item and of any special qualities or effects it might have on the player.<br />
Some if not all of these fields will be filled in automatically when adding from the Compendium (where applicable).<br />
<br />
Both versions of the equipment field have the sections for each of the [https://app.roll20.net/compendium/dnd5e/Treasure#h-Treasure coins] you may find on your adventures: copper(CP), silver(SP), electrum(EP), gold(GP), and platinum(PP).<br />
<br />
====Encumbrance====<br />
If you are following Encumbrance rules, the <span style="font-family:Pictos;">i</span> [[Compendium|Compendium Compatible]] Equipment block will automatically calculate and track the weight of your character's backpack if you enter the weight values for any of the items in your Equipment list. When your character becomes encumbered, and depending on its severity, the words ENCUMBERED, HEAVILY ENCUMBERED, or IMMOBILE will display in red underneath the TOTAL WEIGHT value. You can also choose to follow Simple, Variant Encumbrance rules, or not follow Encumbrance rules at all by toggling it off on the [[D&D 5E by Roll20#Settings Page|Settings Page]] under "General Options".<br />
<br />
====Mods====<br />
The Mods field of each piece of equipment can modify the values of ability scores, AC, saving throws, Skill (Ability) checks and more. What follows is a list of the modifiers, and the proper syntax for adding them.<br />
<br />
All modifiers are separated by commas. There are other modifiers that can appear the mod field, used in creating the item from a compendium drag and drop operation, but the modifiers below have live effects on the character sheet, depending on if the item is marked as “equipped”.<br />
<br />
'''replace the <code>+n</code>, with the number you want.''' For example, if you want to boost Animal Handling skill by 3, you look at the table and find <code>Animal Handling +n</code>, so you will add to your item <code>Animal Handling +3</code>.<br />
<br />
{| class="wikitable" <br />
|-<br />
! Modifier<br /><br />
! Effect<br /><br />
|-<br />
| style="width: 20%;" | '''Combat Modifiers'''<br />
| '''These affect items that provide attacks (Appear in the attack section of the character sheet)'''<br />
|-<br />
| Melee Attacks +n<br />
| Adds +n hit "Magic Bonus" to that attack. It is not global, and only affects a weapon(melee or ranged), not an item, staff or other category. The bonus is figured into the attacks display on the 5e sheet.<br />It is NOT ''Melee Attack''.<br />
|-<br />
| Melee Damage +n<br />
| Adds +n damage "Magic Bonus" to that attack. It is not global, and only affects a weapon(melee or ranged), not an item, staff or other category. The bonus is listed separately in the attacks display on the 5e sheet.<br />
|-<br />
| Spell Attack +n<br />
| Adds a global +n to the character's Spell Attack bonus.<br />It is NOT ''Spell Attacks.''<br />
|-<br />
| '''Saving Throws'''<br />
| '''All modifiers stack with “Saving Throws +n'''<br />
|-<br />
| Strength Save +n,<br />Dexterity Save +n,<br />Constitution Save +n,<br />Intelligence Save +n,<br />Wisdom Save +n,<br />Charisma Save +n<br />
| Adds a +n to the indicated saving throw<br />''Do not use a colon.''<br />
|-<br />
| Saving Throws +n<br />
| Adds a Global Modifier to ALL saving throws.<br />
|-<br />
| Spell DC +n<br />
| Adds a global +n to a spell casting character’s Spell Save DC.<br />It is NOT Spell ''Save'' DC.<br />
|-<br />
| '''Ability Scores'''<br />
| <br />
|-<br />
| Strength +n,<br />Dexterity +n,<br />Constitution +n,<br />Intelligence +n,<br />Wisdom +n,<br />Charisma +n<br />
| Provides a bonus to the indicated ability score, which will appear in blue on the sheet while the bonus is active.<br />Do not use a colon. ''Strength: +10'' will do nothing<br />
|-<br />
| Strength n,<br />Dexterity n,<br />Constitution n,<br />Intelligence n,<br />Wisdom n,<br />Charisma n<br />
| Replaces the indicated ability score, which will appear in blue on the sheet while the bonus is active.<br />Do not use a colon. ''Strength: 10'' will do nothing<br />
|-<br />
| '''Skills'''<br />
| <br />
|-<br />
| Acrobatics +n,<br />Animal Handling +n,<br />Arcana +n,<br />Athletics +n,<br />Deception +n,<br />History +n,<br />Insight +n,<br />Intimidation +n,<br />Investigation +n,<br />Medicine +n,<br />Nature +n,<br />Perception +n,<br />Performance +n,<br />Persuasion +n,<br />Religion +n,<br />Sleight of Hand +n,<br />Stealth +n,<br />Survival +n<br />
| Adds the value to the indicated Skill roll. Note that in this case, the <code>+</code> and a colon are optional. <code>Acrobatics +5</code>, <code>Acrobatics 5</code>, <code>Acrobatics: +5</code>, <code>Acrobatics: 5</code> will all add <code>5</code> to the character’s Skill roll. For consistency and to guard against future functionality, it’s probably best to follow the format for ability scores, and use a plus sign with no comma: <code>Acrobatics +5</code>.<br />There is no Global Skill modifier<br />
|-<br />
| '''AC'''<br />
| <br />
|-<br />
| AC +n<br />
| By itself, <code>AC: 13</code> adds 13 to the character’s Armor Class. It does not replace it. <br /><br />If <code>Shield</code>, <code>Light Armor</code>, <code>Medium Armor</code>, or <code>Heavy Armor</code> is also in the mods field, it will change the calculation.<br />''<code>Light Armor, AC: 13</code>'' will give a formula of 13 + dex mod<br />''<code>Medium Armor, AC: 13</code>'' will give a formula of 13 + dex mod (max +2)<br />''<code>Heavy Armor, AC: 13</code>'' will give you flat AC 13<br />''Shield, AC: 13'' would add 13 to the your AC. The Shield keyword is superfluous in this case.<br />''<code>Shield, AC: 2</code>'' will just add 2 to the AC.<br />Finally, a bare modifier, such as for a Ring of Protection can just be written as <code>AC: +2</code> or <code>AC +1</code>.<br /><br />Shield or bare AC bonuses will stack with other armor mods on different items. You cannot equip multiple armors simultaneously, or have a custom armor equation on the settings tab and wear an armor. This will generate a flag.<br /><br />The + and a colon are semi-optional. <code>AC +5</code>, <code>AC: +5</code>, <code>AC: 5</code> will all work. However, <code>AC 5</code> will do nothing. For consistency and to guard against future functionality, it’s probably best to indicate a base AC as <code>AC: n</code> and a Shield as <code>AC +n</code>.<br />At this point, there is no way to differentiate between Ranged AC and Melee AC, though some magic items such as the ''Arrow Catching Shield'' make the distinction.<br />
|}<br />
<br />
<br />
<br />
<div style="clear: both"></div><br />
<br />
===(17) Features & Traits===<br />
[[File:5E OGL Sheet Features Traits.png|thumbnail|left|The Compendium Compatible itemized version of the Features & Traits section]]<br />
The '''Features and Traits '''-block is the place to store '''Class-''', '''Race-''' and '''Background Features''', '''Feats''', and other special notes about your character or of a certain piece of equipment or ability. When using the Charactermancer, the previously mentioned features appears in this section.<br />
<br />
This block can be set up to be <span style="font-family:Pictos;">i</span> [[Compendium|Compendium Compatible]] (where you can add repeating sections for individual items) or as one resizable free-text field to enter whatever you wish in here. You can adjust this block's behavior by going to the [[D&D 5E by Roll20#Settings Page|Settings Page]] of the sheet and going to the '''General Options'''-block to change whether this block uses the Simple or Compendium Compatible layout. <br />
<br />
When adding items to the Compendium Compatible version of this block, you have the <code>Name</code> field, a <code>Source</code>-field where you can choose between (Racial, Class, Feat, Background, or Other) , a <code>Source Type</code>-text field to describe the type, and then the multilined <code>Description</code>-textbox. Clicking on the <span style="font-family:Pictos;">y</span>(gear)-icon in the top right corner of the item will lock/unlock the item's editability. When locked down, a <span style="font-family:Pictos;">w</span>(chat bubble)-icon appears when you mouse over the feature/trait. Clicking on the <span style="font-family:Pictos;">w</span> will share this feature's description in the {{Text Chat}}.<br />
<br />
There presently isn't a means to format the raw text (italicize, bold, font alignment, etc) of the Simple version or in the Description section of either version of the Features & Traits block.<br />
<br />
You can drag-n-drop '''Feats''' from the compendium, even though they can't be selected in the Charactermancer on levelup.<br />
<br />
PC Features and Traits can be called using an ability roll:<br />
<code>%{selected|repeating_traits_$0_output}</code><br />
Simply increase the $0 value to access all Features and Traits listed on the character sheet, $1, $2, $3...<br />
<br />
<p style="clear:both;"></p><br />
<br />
==Bio Page==<br />
[[File:D&D5E-Roll20-BIO-tab.png|right|thumb|250px|The Bio Page of the PC Sheet]]The Bio page, opened by selecting "BIO" from the 4 buttons near the top right of the sheet, is comprised of free-form text fields that can be used to keep track of less "structured" information about your character. You can use this page to describe your character's appearance, keep track of who their allies are and what organizations they've worked for, and on this page is a section to supplement the inventory list, on the front page, with the "Treasure" section, where you can keep track of all the loot you find along your travels.<br />
===Bio Header===<br />
[[File:D&D5E-Roll20-Bio-header.png|550px]]<br /><br />
<br />
The header of the Bio page contains the basic run down of a character's physical appearance.<br />
*'''Character Name:''' This is carried over from every single PC Page and matches the character journal's name<br />
*'''Age:''' The character's current age<br />
*'''Size:''' The size classification for the race type (Medium for most cases)<br />
*'''Height:''' The character's height<br />
*'''Weight:''' The character's weight<br />
*'''Eyes:''' The character's eye color<br />
*'''Skin:''' The character's skin color<br />
*'''Hair:''' The character's hair color/style<br />
<br />
===Character Appearance===<br />
While the Bio Header describes the bare bone physical characteristics of a PC, this field is for fleshing out the visual peculiarities and/or cues of your character. Does you character have a piercing gaze? A stooped posture? Are they fancily dressed or are their clothes moth-eaten? In essence, this field is for everything and anything one would note about the character–from the equipment or garb they wear to how they comport themself.<br />
<br />
===Allies & Organization===<br />
This text field is for listing important or campaign relevant NPCs that the character may have a connection with. It's also for keeping track of faction allegiance. In the case of ''Dungeons & Dragons''' Forgotten Realms world, a PC could be a member of the Harpers or the Emerald Enclave, among other major factions who are all vying for power of the continent.<br />
<br />
===Character Backstory===<br />
This field is for listing your character's pre-campaign history, their relations, and the pertinent places they have been to in the past.<br />
<br />
===Additional Features & Traits===<br />
This text field is a continuation of the [[#.2817.29_Features_.26_Traits | Features & Traits]] section of the Core Page. The section on the Core Page is a good place for commonly utilized features of a character or briefly jotting down an abbreviated list. This field on the Bio page gives you more real estate to fully write down everything you need in whole.<br />
<br />
===Treasure===<br />
This text field is where you can list all the loot you've collected while searching bodies and delving through dungeons. Since much of these effects are transient and are likely to be used, given away, or sold to the highest bidder at the earliest opportunity, this may be preferable place to keep this list of items rather than adding them to the itemized Compendium Compatible Equipment section (if you have that version enabled).<br />
<br />
==Spell Page==<br />
[[File:D&D5E-Roll20-Spells-tab.png|right|thumb|400px|The Spell Page]]The Spell page, opened by selecting the "SPELLS" button from the four buttons near the top right of the sheet, is used to keep track of all of the powerful magics at your character's fingertips.<br />
<br />
===Spell Page Header===<br />
[[File:D&D5E-Roll20-Spells-header.png|550px]]On the Spells page Header you can set the ability modifier that will be used for casting spells. Selecting the Spellcasting Ability block will allow you to select an attribute from a dropdown, and this will be used in all relevant spell rolls. This attribute will be set automatically when you select a spell casting class. The next two blocks, the Save DC and Attack Bonus will be set automatically based on the class that is selected on the Core page.<br />
<br />
===Spellcasting Ability===<br />
The Spellcasting Ability modifier will automatically update, depending on the class you select on the Core page, to the correct ability modifier for your class. If, for some reason, you need to change this value you can click on the modifier listed in this section and it will give you a drop-down list of all available ability modifiers.<br />
<br />
===Spell Save DC & Attack===<br />
The Spell Save DC and Spell Attack Bonus sections cannot be changed manually, but are just a visual output of modifiers that will be happening behind the scenes. The Spell Attack Bonus is the number that will be added to all spell attack rolls, automatically.<br />
<br />
The Spell Save DC refers to the Save DC that enemies will have to beat when they are trying to dodge/resist your incoming spells. Say, Fred the Sorcerer casts Lightning bolt, and his Spell Save DC is 14. Any enemies hit by his attack will have to make a DEX save and try to beat 14. If they manage to beat the attack, then they are only grazed and take half of the damage. If they don't beat 14, then they take the full damage of the attack instead.<br />
<br />
===Spell Levels & Spells Per Day===<br />
The main section of the Spells page lists 10 sections, ranging from 0 to 9, representing the Cantrips (0) and spells level 1 - 9 where the level of the spell is listed in the triangle on the left of each section header. The number in the left square of the header represents the total number of Spell Slots, in other words, the maximum number of times a spell of this level can be cast in between long rests. This number will be set automatically depending on the level of your character, but can be modified by clicking the up or down arrow or just entering a number in the space provided. The number in the right-most box in the headers is the Slots Remaining value that can be used for you to keep track of the number of times you've cast a spell at this level.<br />
<br />
===Adding Spells===<br />
[[File:D&D5E-Roll20-Spells-Icons.png|framed|right]]<br />
When you drag spells from the <span style="font-family:Pictos;">i</span> [[Compendium]] to the sheet, a new spell entry will be added to the Spell Page under the appropriate level header. This will copy over all corresponding information linked to the spell, as well as creating an attack entry in the [[D%26D_5E_by_Roll20#.2811.29_Attacks_.26_Spellcasting|Attacks & Spellcasting]]-block on the "Core" page, if the spell can be used as an attack. The name of the spell will be listed to the left of the entry and to the right are icons for whether the spell is a Ritual (R), requires Concentration (C), and lists whether there is a Verbal (V), Somatic (S), or Material (M). There is also a circle at the far left of the entry that can be toggled to be filled in with red or left empty. This toggle represents spells that are Prepared for the day and are available for a player's convenience to help track this.<br />
<br />
You can manually add spells by selecting the <span style="font-family:Pictos;">&</span> under any of the Spell Level headings. This will present you with a blank template where you can enter all of the information about a spell. By default, the spell card only contains non-attack information about a spell. If the spell IS an attack you can change the "Output" selector from "Spellcard" to "Attack", this will show some additional input fields to fill out the attack information about the spell. Switching this input will also add an attack entry to the [[D%26D_5E_by_Roll20#.2811.29_Attacks_.26_Spellcasting|Attacks & Spellcasting]]-section on the [[#Core Page|Core page]] so this spell attack can also be cast from the main page. All of these sections are linked, so changing information in one place will also change the corresponding information in the other location. To save your edits, click on the gear icon at the upper right of the entry to collapse the spell entry.<br />
<br />
You can edit any spell at any time, by hovering your mouse over the entry to make a <span style="font-family:Pictos;">y</span> icon appear on the left. Clicking on the <span style="font-family:Pictos;">y</span> will roll out the spell once more to be edited.<br />
<br />
==Settings Page==<br />
[[File:D&D5E-by-Roll20-Settings-Page.png|thumb|right|400px|The Settings tab of the sheet, accessed from the '''<span style="font-family:Pictos;">y</span>''' icon ]]<br />
The Settings page, accessed by selecting the <span style="font-family:Pictos;">y</span>(gear) icon from the four buttons near the top right of the sheet, is where you can make changes to some parts of your character sheet that aren't represented on the other pages.<br />
<br />
===Class Options===<br />
In the class options section is where you have access to some important parts of your character, that usually are managed in the background. They are placed here so that, if needed they can be modified as well.<br />
<br />
'''Hit Dice:''' This section will be set automatically depending on the class chosen on the [[#Core Page|Core page]], but can be changed here by selecting the value and choosing a new one from the drop-down menu. This option is used whenever the "Hit Dice" section is used on the Core page.<br />
<br />
'''Carrying Capacity Modifier:''' This modifier allows you to increase the weight that a character can carry before they become encumbered.<br />
<br />
'''Global Magic Attack Modifier:''' This modifier will affect all spell attacks rolled from the sheet.<br />
<br />
'''Magic Caster Level:''' By default, a character's caster level is tethered to their class level. This option allows you to set the caster level manually, so you can have it differ from the character's class level. This will automatically change the Spell Slots Total for each spell level on the [[#Spell Page|Spells page]].<br />
<br />
'''Spell Save DC Mod:''' The Spell Save DC is normally a field you can't edit from the Spell page and is set by the character's class and level. This modifier allows you to alter that value.<br />
<br />
'''Spell Icons:''' This option will allow you to choose to turn off all the Spell Icons (R, C, V, S, & M), show them all, or only display only the ritual and concentration icons.<br />
<br />
'''Halfling Luck:''' Use this checkbox if your character is a Halfling that happens to take advantage of the Halfling Luck race feat. Using this feat will automatically re-roll any 1s rolled for attacks and skills or ability checks/saves.<br />
<br />
'''Arcane Fighter/Rogue:''' These checkboxes can be used to keep track of when your Fighter or Rogue-classed character actually has access to spells.<br />
<br />
===Multiclass Options===<br />
If you are taking advantage of the D&D 5E multiclassing you can keep track of it in this section. Any levels to your character's additional classes must be changed here, and will then be reflected in the header portion of the sheet. Once you've added additional classes in this section, any time you roll Hit Dice from the Core page it will ask you which classes hit dice you wish to use.<br />
<br />
Note: Be sure to not re-include your main class in this section, or your final level calculation will be incorrect.<br />
<br />
===Custom Class Options===<br />
If you are playing a class that is not part of the D&D 5E Compendium, you can input the important class information in this section, and checking the "Use Custom Class" checkbox will replace the main class selection with your custom built class.<br />
<br />
===Spell Slot Modifiers===<br />
This section allows you to manually modify how many spell slots your character has available for each spell level from 1 to 9.<br />
<br />
===Attribute Options===<br />
'''Attribute Modifiers:''' With this section you can manually adjust the individual Attribute Scores for Strength, Dexterity, Constitution, Intelligence, Wisdom, and Charisma.<br />
<br />
'''Initiative Modifier:''' Usually, your initiative modifier is just based off of your DEX modifier, but if you happen to find a magical item that enhances these rolls this is where you will put that bonus. This modifier will be used whenever the [[#.287.29_Armor_Class.2C_Initiative.2C_.26_Speed|Initiative]]-section is rolled on the Core page.<br />
<br />
'''Initiative Style:''' This setting allows you to select whether Initiative will be rolled with Advantage, Disadvantage, or rolled normally with a single d20 (default).<br />
<br />
'''Add DEX Tiebreaker to Initiative:''' If you would like to enable a tie breaker component to Initiative, this checkbox will enable adding your dexterity Attribute Score as a decimal value to your Initiative roll. So if you have a character with a dexterity attribute score of 14, your initiative modifier will change from a 2 to a 2.14.'<br />
<br />
'''Global Armor Class Modifier:''' This setting will modify your armor class and will be taken into account regardless of the equipment the character uses.<br />
<br />
'''Armor Class Tracking:''' There are three options available: The Automatic version that's default to the sheet where it adds 10 + your DEX modifer and then takes any armor equipped into account. A Custom version which expands out a formula upon selection where you can input your own formula for armor tracking, or you can turn Off Armor Tracking entirely. When turned off, you will need to manually adjust the Armor Class field on the Core page.<br />
<br />
===Save Options===<br />
'''Save Modifiers:''' With this section you can manually adjust the individual Save modifiers for Strength, Dexterity, Constitution, Intelligence, Wisdom, and Charisma.<br />
<br />
'''Death Save Modifier:''' A normal death save is usually just a D20 against a dc of 10, but if you're lucky enough to have a bonus to death saves, this is where you will put your bonuses. This modifier will be represented any time a "Death Save" is rolled from the Core page.<br />
<br />
'''Global Saving Throw Modifier:''' If you have an affect that would modify all saving throws, this option makes it easier to adjust your Save modifiers than having to go in and change each one individually. This modifier will be used every time any save is rolled from the sheet.<br />
<br />
===Skill Options===<br />
If your class offers the ability to achieve "Expertise" in a skill, or if you are using a Bard with the "Jack of All Trades" feat, this is where you will make these adjustments. There is also a section to add flat modifiers to any of your skills if your character has an archetype ability like Remarkable Athlete or a feat that adds a flat bonus to a skill. You can add expertise to any skill by clicking the value next to it and choosing "Expertise" from the drop-down menu. If your Bard has the Jack of All Trades feat, you can check the checkbox at the bottom of this section and it will automatically give half of your character's proficiency points to any skill check that doesn't have full proficiency.<br />
<br />
'''Passive Perception Modifier:''' This option will add a bonus to a character's Passive Perception which is not something you can change directly from the Core page of the sheet.<br />
<br />
===General Options===<br />
The General Options section has some important options that deal more with how the sheet works, rather than actual character creation. Most importantly, the NPC checkbox at the top, which will change the sheet to be the NPC version which is shaped to more easily track an NPC's information.<br />
<br />
'''Roll Queries - Always/Toggle/Query/Never Roll Advantage:''' This option will change how advantage is rolled for all attacks. It defaults to always roll advantage, which means that every time an attack is rolled it will roll twice and present the outcome of both rolls. This is useful for both advantage and disadvantage, otherwise you can just choose either the left or the right to be the default roll. Toggle adds a set of buttons at the top of the sheet to manually switch your advantage options between rolls. If Query is chosen, every time a roll is made it will ask you whether or not it's advantage. If Never is chosen, then it will always roll just a single dice per attack roll.<br />
<br />
'''Whisper Rolls to GM:''' Like above, you have the option to Never/Toggle/Query/Always whisper rolls to the GM. When this option is enabled, the attack roll will only be whispered to the GM and not made public.<br />
<br />
'''Auto Damage Roll:''' By default, damage rolls will not be rolled automatically, but only when you click the attack in the chat window. This is useful because you can choose to only roll damage when an attack hits. Using this option you can make the character always roll damage with every attack.<br />
<br />
'''Core Die Roll:''' You can change the core die (by default it is 1d20) to something else entirely here.<br />
<br />
'''Proficiency Bonus:''' By default, the character's Proficiency Bonus is calculated by class level. This setting allows you choose to calculate this bonus via By Level (the default), via a Proficiency Die as described in the Dungeon Master's Guide, or a Custom calculation which rolls out a field to enter a roll formula for the bonus.<br />
<br />
'''Global Save/Skill/Attack/Damage Modifier Field:''' This series of checkboxes will add new entries to the Saving Throws, Tools Proficiencies & Custom Skills, and Attacks & Spellcasting blocks respectively to add global modifiers (like if a character is under the effects of a Bless or Guidance spell). Each entry will have a Global label in grey at the bottom of its entry and a field to enter the modifier bonus. If you include a word in brackets with the bonus formula (ex. "1d4[Bless]"), the word enclosed in the brackets will appear when you mouse over a roll to see it's formula.<br />
<br />
'''Add Character Name to Templates:''' This option allows you to turn this on or off. When it is on, the character's name is listed in the roll template when rolls are made from the sheet. If the character sheet in question is for an NPC, you will likely want to have this off so the rolls don't accidentally show your hand of what sort of monster your party is facing. This setting is off by default.<br />
<br />
'''Auto Level Calculations:''' This option allows you to turn this on or off. When it is on, adjusting the character's class level will automatically update the character's proficiency bonus, Hit Dice, and spell Slot totals (if the class is a spellcaster).<br />
<br />
'''Encumbrance:''' This option dictates how encumbrance is handled on the Equipment block of the Core page. This requires your Inventory to be set to "Compendium Compatible" to automatically calculate and track the weight of your character's backpack if you enter the weight values for any of the items in your Equipment list. When your character becomes encumbered, and depending on its severity, the words ENCUMBERED, HEAVILY ENCUMBERED, or IMMOBILE will display in red underneath the TOTAL WEIGHT value. This setting has three options: Simple Encumbrance Rules, Variant Encumbrance Rules, or not follow Encumbrance rules at all by toggling it off from this.<br />
<br />
'''Inventory:''' With this option allows you to either have your Equipment block be "Compendium Compatible" or "Simple". The Simple version of the Equipment block will give you single text field to log your inventory. The Compendium Compatible version tracks weight, quantity, and attack options in an itemized list for every equipment item you add to the block.<br />
<br />
'''Features & Traits:''' This option can set the Features & Traits block to be either a single text field or a repeated section that will be Compendium Compatible to list traits and features in an itemized list.<br />
<br />
'''Proficiencies & Languages:''' This option can set the Proficiences & Languages block to be either a single text field or a repeated section that will be Compendium Compatible to list traits and features in an itemized list.<br />
<br />
'''Ammo Tracking (API Required):''' When using the 5th Edition OGL Companion API Script in your game (Pro Subscriber feature), you can set attacks to weapons using ammunition to automatically subtract from their tally in their Resource block. So if your character is equipped with a bow, rolling its attack will automatically remove an arrow from its Resource block.<br />
<br />
===Transition Options(outdated)===<br />
{{mbox | text = This feature doesn't seem to exist on the sheet any longer, so the info in this section is outdated}}<br />
<br />
If your campaign previously used the [https://wiki.roll20.net/DnD5e_Character_Sheet#Intro Community Contributed] or [https://wiki.roll20.net/index.php?title=DnD5e_Shaped_Character_Sheet&oldid=11112#General_Information Shaped Legacy] 5th Edition Character Sheets and you are swapping over to this one, we have an automated conversion tool that will clear or merge elements left over from those two sheets. This procedure can only be done ''once'' and can not be undone. It is recommended that you make a copy of your campaign first before attempting a sheet transition.<br />
<br />
There is also a checkbox that hides this feature entirely from the sheet. If you hide this by mistake, you can gain access to it again by creating a new character journal.<br />
<br />
=The NPC Sheet=<br />
''See Also:'' '''[[D&D5E by Roll20 NPC Attributes]]'''<br />
<br />
One of the most useful parts of the D&D 5E by Roll20 Character Sheet is that it contains both a PC sheet ''AND'' an NPC sheet. An NPC doesn't normally require the depth a PC sheet needs, so the NPC sheet is a much more slimmed down character sheet that doesn't require multiple pages like its PC counterpart. You can access this version of the sheet by going to the Settings Page, by clicking the gear icon near the top right of the sheet, and then checking the NPC checkbox. This will switch the sheet to the NPC version. You can switch back at any time by unchecking the NPC option under General Options on the new page.<br />
<br />
==NPC Options==<br />
[[File:5E_OGL_Sheet_NPC_Options.png|right|thumb|250px|The NPC Options Section]]This is the area where all of the NPC's stats will be entered, it covers everything from the NPC's name, to how strong or quick or smart it is, to what languages it speaks. Most of the fields in this section are just text fields used to keep track of information about the NPC. All of the information entered in these fields will be visible in the stat block once the NPC options are hidden. <br />
<br />
<br />
Any text that appears in light grey is placeholder text. It's there to offer you an example of what the content would be for any given field. <br />
<br />
By default, no skill or ability checks will show up in the NPC's stat block. Once you've added a value to the corresponding skill or ability save, they will appear. If for some reason the NPC will have to make a check with a skill or ability it does not have any bonus in, you can enter a 0 as the modifier for that check and it will add it to the list in the stat block below.<br />
<br />
The XP of an NPC auto-calculates based on its given challenge rating.<br />
<br />
If the NPC is a spellcaster, you can check the checkbox beside '''SPELLCASTING NPC''' and this will add a spell list section that utilizes the spell list and its functionality from the PC version of the sheet.<br />
<br />
At default, you can add Traits and Actions in their respective places after the Challenge Rating and XP area of the Stat Block. For Reactions and Legendary Actions, you need to enable them from the NPC Options section. For Reactions, check off the '''HAS REACTIONS''' checkbox. This will add a new sections to the Stat Block for you to add Reactions to. If an NPC is a monster with Legendary Actions then you must enter the number of actions that monster has access to each turn in the '''LEGENDARY ACTIONS:''' field. Once you add a number here, an additional section will appear in the stat block below, where you can add the specific legendary actions that the monster is able to do.<br />
<br />
The NPC sheet supports Compendium drag & drop. If you want to add a new monster to your game just drag the monster from the <span style="font-family:Pictos;">i</span> [[Compendium]]-tab of the [[Sidebar]] and drop it to anywhere on the Tabletop. This will automatically create a new journal entry named the same as the Compendium entry and will copy all of the information on that compendium page directly into the new sheet. If you have purchased any of the Compendium expansions that expands on the available NPCs like the Monster Manual or Volo's Guide to Monster, a token of that NPC will be added to the Tabletop that will have its stats automatically set and linked to the new journal entry.<br />
<br />
{{mbox | text = '''Note:''' If you already have a journal entry in your {{journal}}-tab with the exact same name as the <span style="font-family:Pictos;">i</span> [[Compendium]] entry, the drag and drop will not work as this automation will stop to prevent overwriting existing content the user has already created. If a drag and drop of an NPC Compendium page does not create a journal entry, run a search for that NPC's name in your Journal to see if an entry already exists. If you do not want to delete the older entry, renaming it will allow the drag and drop to work as expected.}}<br />
<br />
===General Options===<br />
Within the NPC Options section, directly below the Legendary Actions field, is the General Options that are featured on the PC Sheet: NPC checkbox, WHISPER ROLLS TO GM, and the AUTO DAMAGE ROLL options. <br />
<br />
*NPC checkbox<br />
*WHISPER ROLLS TO GM<br />
*AUTO DAMAGE ROLL<br />
*NPC NAME IN ROLLS<br />
*ADD DEX TO TIEBREAKER TO INITIATIVE<br />
<br />
Unchecking the NPC checkbox from here will revert the sheet back to the PC Sheet.<br />
<br />
===Hiding NPC Options===<br />
Once all of the desired information has been entered, you can click the <span style="font-family:Pictos;">y</span>(gear) icon at the top right to hide this section. This leaves behind just the NPC's stat block where you can make all of your rolls from. You can re-open this section to edit the information at any time by clicking on the <span style="font-family:Pictos;">y</span> icon again. It's in the same location regardless if you're looking at NPC Options or the NPC stat block.<br />
<br />
==The NPC Stat Block==<br />
[[File:5E OGL Sheet NPC v2.png|right|thumb|250px|An NPC stat block for a griffon]]Following NPC Options is the NPC Stat Block that is built off of what you input in the NPC Options section. This area may look very similar to a stat block you may find in a monster bestiary or published adventure.<br />
<br />
<br />
Any section of the stat block that has a corresponding roll will have click-able text. For example, if the NPC has to make a CON check, you can click the CON attribute to roll a CON check with all of the required modifiers automatically included. If you added a value to one of the skill modifier fields then that skill will show up in the NPC's "Saving Throws" list where you can click it to make a saving throw roll using that skill's modifier.<br />
<br />
The first section of the Stat Block mirrors all the information you added in the NPC Options section. This content is meant exclusively for rolling and can not be edited directly. You will need to change them from the NPC Options section.<br />
<br />
===Traits===<br />
Traits are pieces of information about an NPC that isn't covered by the NPC options section. These are entered directly onto the NPC's stat block. If you click the "<span style="font-family:Pictos;">&</span>" button that appears right below the "Senses/Languages/Challenge Rating" section it will add a blank entry where you can add a single trait for that NPC. Each Trait Entry features a bold title field which is then followed by a larger text box for the description of the trait. You can add any number of Traits for any NPC.<br />
<br />
===Actions===<br />
NPC actions can be used for any number of things. Each entry initially offers an Action Name field as well as a large text field for the Action description. The checkbox for ATTACK, once checked, adds more structured data fields needed for an attack roll (Type, Range/Reach, To Hit bonus, Target, Damage Roll, and Damage Type). To add a new entry you will select the <span style="font-family:Pictos;">&</span> button that appears below the Actions section. Once all of this is complete you can click the <span style="font-family:Pictos;">y</span>(gear) icon at the top of this entry to hide the input fields, leaving just the action text. You can show this information, or roll the attack, in the chat box by clicking the text for the action. If you need to make further modifications to any action you can hover over the row you wish to edit, then click on the <span style="font-family:Pictos;">y</span>(gear) icon again. This will show all of the action information input fields again. You can add any number of Actions for any NPC.<br />
<br />
===Bonus Actions===<br />
NPC bonus actions are typically not listed on the sheet, and are usually referenced in the Traits section. However, if a player wishes to use this section, it is available if the 'Bonus Action' checkbox is selected. The fields work the same as the Actions section.<br />
<br />
===Reactions===<br />
Once enabled from the NPC Options section, a new heading labeled "Reactions" and its relevant section is added to the stat block that allows you to add Reactions. These entries operate just like Traits.<br />
<br />
===Spells===<br />
Once enabled from the NPC Options section, a new heading labeled "Spells" and its relevant section is added to the stat block that allows you to add Spells. These entries will operate identically to how Spells are added and handled on the PC Sheet with the one noted exception that there is only a single column of spell entries. You can drag spells from the Compendium to add spell entries just like you would with the PC's Spell sheet. Any and all spells added to the character sheet are shared between the NPC and the PC versions.<br />
<br />
===Legendary Actions===<br />
If a number value is added to the LEGENDARY ACTIONS field in the NPC Options section, the Legendary Actions heading and section is added at the very bottom of the stat block and lists some verbiage on how many actions are available to be used on a given turn. This number is dictated by what you entered in the NPC Options. These entries operate the same way as Traits.<br />
<br />
==Rolling for Initiative for NPCs==<br />
There are two ways to roll for Initiative on the NPC sheet. You can click on the NPC's Name to roll for Initiative or you can roll from the die icon labeled INIT that is listed to the right of the Armor Class and Hit Points section of the NPC sheet, towards the top. If you have the Turn Tracker tool open, having the NPC token selected while rolling Initiative will automatically add the NPC and its initiative roll to the tracker. Creatures on the GM layer that are added to the tracker in this fashion will have their entries hidden from the players.<br />
<br />
<br />
You can also create a global Macro that will pop up as a Token Action button in the upper left hand corner of the tabletop every time a token is selected. This will allow you to roll without looking at the NPC sheet at all. The macro formula should look just like this:<br />
<br />
<code>%{selected|npc_init}</code><br />
<br />
=Advanced Use=<br />
<br />
===Custom Skills and Stats===<br />
You can set up any number of custom skills or rolls from the [[#Tool Proficiencies|Tool Proficiencies]] section just underneath the skill section on the Core tab. [[#Class & Other Resources|The Resources]] section is also useful for tracking custom stats to your campaign, game setting, or home-brew rules. There are also various options available from the Settings page to modify attributes, skills, saves, spells, and more.<br />
<br />
===Target Roll Buttons===<br />
A useful way for GMs and Players to reference their abilities is by dynamically setting up a handful of macros that can be used on a token linked to a character, rather than having to roll directly from the sheet. To do this, you'll set up a global macro from the {{Collections}}-tab. You can also write these directly in the {{Text Chat}}.<br />
<br />
In the examples, the <code>selected</code> part can be replaced with <code>target</code>, a character's name, or it's character ID.<br />
<br />
Here are some examples:<br />
<br />
'''PC'''<br />
* Attributes: <code>%{selected|strength}</code>, <code>%{selected|strength_save}</code> | Will roll the Strength Check and Strength Save for the selected [[token]](if the [[Link Token|token is linked to a sheet]])<br />
* <code>%{selected|acrobatics}</code><br />
* <code>%{selected|initiative}</code><br />
* <code>%{selected|death_save}</code><br />
* <code>%{selected|hit_dice}</code><br />
<br />
'''NPC'''<br />
* <code>%{selected|npc_init}</code><br />
* <code>%{selected|npc_str}</code><br />
* <code>%{selected|npc_stealth}</code><br />
* <code>%{selected|npc_hpformula}</code><br />
====Dynamic References to Repeating Sections====<br />
The example we'll be using today is setting up the 1st NPC action:<br />
<code>%{selected|repeating_npcaction_$0_npc_action}</code><br />
Now whenever you use this macro it will roll the first NPC action of whichever NPC token you have selected. You can set up a roll for each action by incrementing the 0 by 1 for each action you wish to add (I.E. <code>$1</code>, <code>$2</code>, <code>$3</code>). Here is a list of important repeating section rolls and their formulas:<br />
<br />
* Player Attack/Spell Attack <code>%{selected|repeating_attack_$0_attack}</code><br />
* Player Attack/Spell Damage <code>%{selected|repeating_attack_$0_attack_dmg}</code><br />
* Player Attack/Spell Critical Damage <code>%{selected|repeating_attack_$0_attack_crit}</code><br />
* Player Global DMG mod <code>%{selected|repeating_damagemod_$0_global_save}</code><br />
** Attr names: <code>global_damage_name</code>, <code>global_damage_damage</code>, <code>global_damage_critical_damage</code>, <code>global_damage_type</code><br />
* Proficiencies <code>%{selected|repeating_proficiencies_$0_output}</code><br />
* Tool/Custom Skill <code>%{selected|repeating_tool_$0_tool}</code><br />
* Traits/Feats: <code>%{selected|repeating_traits_$0_output}</code><br />
<br />
* Spellbook Cantrip <code>%{selected|repeating_spell-cantrip_$0_spell}</code><br />
* Spellbook Level 1 <code>%{selected|repeating_spell-1_$0_spell}</code><br />
* Spellbook Level 2 <code>%{selected|repeating_spell-2_$0_spell}</code><br />
* Spellbook Level 3 <code>%{selected|repeating_spell-3_$0_spell}</code><br />
* Spellbook Level 4 <code>%{selected|repeating_spell-4_$0_spell}</code><br />
* Spellbook Level 5 <code>%{selected|repeating_spell-5_$0_spell}</code><br />
* Spellbook Level 6 <code>%{selected|repeating_spell-6_$0_spell}</code><br />
* Spellbook Level 7 <code>%{selected|repeating_spell-7_$0_spell}</code><br />
* Spellbook Level 8 <code>%{selected|repeating_spell-8_$0_spell}</code><br />
* Spellbook Level 9 <code>%{selected|repeating_spell-9_$0_spell}</code><br />
<br />
'''NPC'''<br />
* NPC Traits/Abilities<code>%{selected|repeating_npctraits_$0_npc_roll_output}</code><br />
* NPC Actions/Attacks<code>%{selected|repeating_npcaction_$0_npc_action}</code><br />
* NPC Attack Damage<code>%{selected|repeating_npcaction_$0_npc_dmg}</code><br />
* NPC Attack Critical Damage<code>%{selected|repeating_npcaction_$0_npc_crit}</code><br />
* NPC Bonus Actions<code>%{selected|repeating_npcbonusaction_$0_npc_action}</code><br />
* NPC Legendary Actions<code>%{selected|repeating_npcaction-l_$0_npc_action}</code><br />
* NPC Mythic Actions<code>%{selected|repeating_npcaction-m_$0_npc_action}</code><br />
* NPC Spells<code>%{selected|repeating_spell-npc_$0_spell}</code><br />
<br />
===Directly Referencing Attributes===<br />
You can discover the name of most of the attributes in the sheet by hovering over them. After a couple of seconds a title will pop up and tell you how to referencing them. You can call attributes in an Ability Rolls by using <code>@{attributename}</code>. If you want to directly reference it in a roll that isn't saved on the sheet, you need to specify the character's name, or use either the <code>selected</code> or <code>target</code> key works.<br />
<br />
'''Examples:'''<br />
* <code>/em attempts to grapple and gets [[1d20+@{strength_mod}]]</code> custom [[Journal#Attributes_.26_Abilities_Tab|Ability call]], saved on the A&A-tab<br />
* <code>/r 1d20+@{Alice|strength_mod}+@{Alice|pb}</code> macro that calls a specific character<br />
* <code>/em have @{selected|hp} out of @{selected|hp|max} left.</code> macro that uses stats from a token(token must be selected before rolling)<br />
* <code>The Enemy's AC is @{target|npc_ac}</code> macro prompt the user to select a target token on the map, and uses it's stats.<br />
<br><br />
<br />
See [[Macros#Attribute_Macros]] for further general details/examples on the syntax.<br />
====PC====<br />
Here are a list of some of the more important stats:<br /><br />
<br />
'''Attributes/Saves:'''<br />
<br />
* Str: <code>strength, strength_mod, strength_save_bonus</code><br /><br />
* Dex: <code>dexterity, dexterity_mod, dexterity_save_bonus</code><br /><br />
* Con: <code>constitution, constitution_mod, constitution_save_bonus</code><br /><br />
* Int: <code>intelligence, intelligence_mod, intelligence_save_bonus</code><br /><br />
* Wis: <code>wisdom, wisdom_mod, wisdom_save_bonus</code><br /><br />
* Cha: <code>charisma, charisma_mod, charisma_save_bonus</code><br />
<br><br />
'''Skills:'''<br />
<br />
<code>athletics_bonus<br /><br />
acrobatics_bonus<br /><br />
animal_handling_bonus<br /><br />
arcana_bonus<br /><br />
deception_bonus<br /><br />
history_bonus<br /><br />
insight_bonus<br /><br />
intimidation_bonus<br /><br />
investigation_bonus<br /><br />
medicine_bonus<br /><br />
nature_bonus<br /><br />
perception_bonus, passive_wisdom<br /><br />
performance_bonus<br /><br />
persuasion_bonus<br /><br />
religion_bonus<br /><br />
sleight_of_hand_bonus<br /><br />
stealth_bonus<br /><br />
survival_bonus<br /><br />
</code><br />
<br />
'''AC, Proficiency, HD etc'''<br />
<br />
<code>pb</code>(Proficiency Bonus)<br><br />
<code>inspiration</code><br><br />
<code>ac<br /><br />
initiative_bonus<br /><br />
speed<br /><br />
hp, hp|max, hp_temp<br /><br />
hit_dice, hit_dice|max, hitdietype<br /><br />
weighttotal<br /><br />
</code><br />
<br />
'''Spells'''<br />
<br />
<code>spell_save_dc, spell_attack_bonus<br /><br />
lvl1_slots_total, lvl1_slots_expended<br /><br />
lvl2_slots_total, lvl2_slots_expended<br /><br />
lvl3_slots_total, lvl3_slots_expended<br /><br />
lvl4_slots_total, lvl4_slots_expended<br /><br />
lvl5_slots_total, lvl5_slots_expended<br /><br />
lvl6_slots_total, lvl6_slots_expended<br /><br />
lvl7_slots_total, lvl7_slots_expended<br /><br />
lvl8_slots_total, lvl8_slots_expended<br /><br />
lvl9_slots_total, lvl9_slots_expended<br /><br />
</code><br />
<br />
Spells, repeating sections:<br><br />
<code>repeating_spell-cantrip<br><br />
repeating_spell-1<br><br />
repeating_spell-2<br><br />
repeating_spell-3<br><br />
repeating_spell-4<br><br />
repeating_spell-5<br><br />
repeating_spell-6<br><br />
repeating_spell-7<br><br />
repeating_spell-8<br><br />
repeating_spell-9</code><br> <br />
<br />
Cantrip stats(most should also work for lvl.1-lvl.9):<br><br><br />
Full statname is spell level + (rowID or row number) + attribute name, e.g. <code>repeating_spell-1_$0_spellname</code> is the spell name of your first Lvl 1 spell, <code>repeating_spell-4_$1_spelldescription</code> is the description of your second lvl.4 spell.<br />
<br />
<code>spellname<br><br />
spellrange, spellcastingtime, spelltarget, spellduration<br><br />
spellschool<br><br />
spellritual<br><br />
spellconcentration<br><br />
spellcomp_v, spellcomp_s, spellcomp_m<br><br />
spellcomp_materials<br><br />
spell_ability<br><br />
spelloutput<br><br />
spellattack<br><br />
spelldamage, spelldamagetype, spelldamage2, spelldamagetype2<br><br />
spellhealing<br><br />
spelldmgmod, spell_damage_progression<br><br />
spellsave, spellsavesuccess<br><br />
spelldescription<br><br />
spellclass, spellsource</code><br />
<br />
'''Items'''<br><br />
<code>cp sp ep gp pp</code><br><br />
(copper pieces, silver, gold, electrum, platinum)<br />
<br />
<code>repeating_inventory_$#_itemcount<br><br />
repeating_inventory_$#_itemname<br><br />
repeating_inventory_$#_itemweight<br><br />
repeating_inventory_$#_equipped<br><br />
repeating_inventory_$#_useasresource<br><br />
repeating_inventory_$#_hasattack<br><br />
repeating_inventory_$#_itemproperties<br><br />
repeating_inventory_$#_itemmodifiers<br><br />
repeating_inventory_$#_itemcontent</code><br><br />
<br />
* <code>equipped</code>, <code>useasresource</code>, <code>hasattack</code> are checkboxes, with value 1 if checked.<br />
* <code>itemmodifiers</code> is for of item changes any stats, like <code>AC +2</code> adding +2 to AC when equpped.<br />
* <code>itemcontent</code> is the item description<br />
<br><br />
'''The class_resource and the other_resource'''<br><br />
<br />
<code>class_resource</code> and <code>other_resource</code> are static resources. That is to say, you need to keep in mind that they are NOT a part of the repeating section, even though it definitely looks that way on the character sheet.<br><br />
<br />
You use these to access them<br />
<br />
<code>class_resource</code><br><br />
<code>class_resource_max</code><br><br />
<code>class_resource_name</code><br><br />
<code>other_resource</code><br><br />
<code>other_resource_max</code><br><br />
<code>other_resource_name</code><br><br />
<br />
'''The repeating resources'''<br><br />
<br />
Any resources that appear beneath the "class resource" and the "other resource" are a part of the "repeating resources" section. This section is known for being confusing for beginners, so it deserves a bit of clarification.<br />
<br />
First, keep in mind that this is one section (not two sections, as people often think), and that "repeating_resource" is its section prefix.<br />
<br />
Second, keep in mind that you need to skip past the row with the "class resource" when you're figuring out the address of the row that you want to refer to. So basically, if you want to refer to the row that is directly below the row with the "class_resource", then you would add "_$0" (to form "repeating_resource_$0"). And then the next row after that is "_$1", and so on.<br />
<br />
Third, keep in mind that if you add "_resource_left" (to form "repeating_resource_$0_resource_left"), then you are specifying that you are talking about the CURRENT VALUE of the leftmost resource in that row. And if you add "_resource_left_max", then you are specifying that you are talking about the MAX VALUE of the leftmost resource in that row.<br />
<br />
Here is a complete list of all the fields that you can access in the "repeating_resource" section. Just replace the "#" character with which row you want to access.<br />
<br />
<code>repeating_resource_$#_resource_left</code><br><br />
<code>repeating_resource_$#_resource_left_max</code><br><br />
<code>repeating_resource_$#_resource_left_name</code><br><br />
<code>repeating_resource_$#_resource_right</code><br><br />
<code>repeating_resource_$#_resource_right_max</code><br><br />
<code>repeating_resource_$#_resource_right_name</code><br><br><br />
<br />
<br />
'''Features/Class Traits'''<br />
<br />
<code>repeating_traits_$0_output<br><br />
repeating_traits_$#_name<br><br />
repeating_traits_$#_source<br><br />
repeating_traits_$#_source_type<br><br />
repeating_traits_$#_description<br><br />
</code><br />
<br />
'''Other/Settings:'''<br />
<br />
<br><br />
<code><nowiki>wtype</nowiki></code> (whisper type, can have one of these values:)<br />
* <code><nowiki></nowiki></code> (empty for never whisper)<br />
* <code><nowiki>@{whispertoggle}</nowiki></code> (show the buttons on sheet that can toggle between options)<br />
* <code><nowiki>?{Whisper?|Public Roll,|Whisper Roll,/w gm }</nowiki></code><br />
* <code><nowiki>/w gm</nowiki></code> (always whisper)<br />
<br />
<br />
'''Global modifiers'''<br />
<br />
* <code>repeating_savemod_$0_global_save_roll</code><br />
* <code>repeating_skillmod_$0_global_skill_roll</code><br />
* <code>repeating_tohitmod_$0_global_attack_roll</code><br />
* <code>repeating_damagemod_$0_global_damage_damage</code><br />
<br />
====NPC====<br />
Some stats are the same as for PCs<br />
<br />
<code>npc_name<br><br />
npc_ac<br><br />
hp, hp|max<br><br />
npc_speed<br><br />
npc_challenge<br><br />
npc_xp</code><br />
<br />
Attributes: <code>strength_base, strength_mod</code> (same as PCs)<br />
Saves:<br />
<br />
<code>npc_str_save_base</code>,<code>npc_dex_save_base</code>, <code>npc_con_save_base</code>,<code>npc_int_save_base</code>,<code>npc_wis_save_base</code><code>npc_cha_save_base</code><br />
Skill bonus:<code>npc_acrobatics_base</code>, <code>npc_animal_handling_base</code> etc.<br />
<br />
Damage/Conditions stuff:<br />
<br />
<code>npc_vulnerabilities<br><br />
npc_resistances<br><br />
npc_immunities<br><br />
npc_condition_immunities</code><br />
<br />
Spells:<br />
<br />
<code>npcspellcastingflag</code> (set to "1" if caster, empty otherwise) <br />
<code>spellcasting_ability</code><br />
<code>globalmagicmod </code> (global magic attack modifier)<br />
<code>caster_level</code><br />
<code>spell_dc_mod</code> (spell save DC mod)<br />
<br />
Spells are identical to PC section<br />
<br />
Other:<br />
whisper is same as PCs<br />
<br />
<code>npc_name_flag</code> (show/hide npc name in rolls, value is either <code><nowiki>{{name=@{npc_name}}}</nowiki></code> or <code>0</code>)<br />
<br />
<br />
<sup>Note: anything with the Suffix of <code>|max</code> requires some form of Prefix, such as <code>selected|</code> making the call for such a thing look something along the lines of <code>@{selected|hp|max}</code>. The <code>|max</code> Suffix specifically calls the box on the right of the selected Attribute's Line, for example, you could fill in the Weight Total's 2nd Box with <code>@{strength}*15</code> & whenever you call <code>@{selected|weighttotal|max}</code> it will tell you your 5e standard Maximum Carry Capacity for your current Strength Score.<br />
<br />
===Custom AC Items===<br />
You can add pieces to your inventory and manually give them AC or magic bonuses that will figure into their calculations automatically. Inside the item options is a section for "MODS:". Add <code>Ac +1</code> to add an armor class bonus.<br />
<br />
===Roll Templates===<br />
''Main Article:'' '''[[D&D 5e by Roll20 Roll Templates]]'''<br />
<br />
The '''D&D5E by Roll20''' Character Sheet also includes a series of [[Roll Templates]] that you can use to dress up your own custom macros. Roll Templates provide additional layout and styling options for the display of roll results.<br />
<br />
{{ex}}<br />
[[File:5e-rolltemplate-ex1-2021.png|200px|right|none]]<br />
Rolls stealth for selected npc token, using it's stealth proficiency.<br />
<code><nowiki>/w gm &{template:npcatk} {{attack=1}} {{name=Shadow}} {{rname=Shadow Stealth}} {{rnamec=Hide}} {{r1=[[@{selected|d20}+@{selected|npc_stealth} + 6]]}} {{always=1}} {{r2=[[@{selected|d20}+@{selected|npc_stealth} + 6]]}} {{description=While in dim light or darkness, the shadow can take the Hide action as a bonus action. Its stealth bonus is **also** improved to +6 }}</nowiki></code><br />
<br />
===Magic Missile Spell===<br />
{| role="presentation" class="wikitable mw-collapsible mw-collapsed" style="float:right; margin-left: 10px;margin-right: 60px;"<br />
| Image of the Spell's settings<br />
|-<br />
| [[File:Magic-Missile-5E-2020.png|right|frame|The Magic Missile Spell]]<br />
|}<br />
<br />
RAW, Magic Missile is rolled once, and the single roll is then used for each hit. So by default the spell rolls <code>1d4+1</code>. (See [[Talk:D&D 5E by Roll20#Old Magic Missile Discussion]] for more info.)<br />
<br />
You can modify the spell to instead roll 3d4+3 at first level, and then in the ''HIGHER LVL CAST DAMAGE'' section, set it to <code>1d4+1</code>.<br />
<br />
To automatically use higher-level spell slots with Magic Missile, you have to write a 0 into the ''HIGHER LVL CAST DAMAGE'' section of the spell and select any die. It will show the box for selecting higher-level spell slots when launching Magic Missile, but since it multiplies the higher-level damage cast by 0, the added roll doesn't show up in the chat, making it roll a single die for every missile while using any level spell slot.<br />
<br />
=API=<br />
{{pro only|section}}<br />
[[API:Introduction|API Scripts]] allow for greater customization and functionality to how Roll20 operates beyond what it can do at default. This section will list some info on using various APIs that interact with the character sheet.<br />
<br />
Example of APIs from the One-Click Install menu, that designed to be used with the '''D&D 5E by Roll20''' sheet:<br />
* '''5E BattleMaster'''<br />
* '''5E Resting in Style'''<br />
* '''CashMaster'''<br />
* '''Concentration'''<br />
* '''[[Script:It's a Trap|It's a Trap! -- D&D 5E Generic]] (should detect automatically what sheet is used)<br />
** {{repo|Roll20/roll20-api-scripts/tree/master/ItsATrap_theme_5E_Generic#readme readme}}<br />
* '''ShortRest'''<br />
* '''SpellMaster'''<br />
* '''WildShape'''<br />
<br />
A good number of the more general APIs have built in settings for configuring them for usage with the 5E sheet, such as '''GroupInitiative''', '''GroupCheck''', '''Experience Tracker''', '''[[PowerCards]]''' <br />
<br />
* '''[[GroupCheck]]:''' <code>!group-check-config --import 5E-OGL</code> will configure the API for use with this sheet<br />
* '''[[GroupInit|GroupInitiative]]:''' before use, API need to be configured for the sheet, either through the menu preset, or using the command: <code>!group-init --add-group --Bare </code><br />
* '''CombatMaster:''' is by default configured with conditions for D&D 5E<br />
* '''[[ChatSetAttr]]:''' API that can create, edit, & delete stats on sheets. Example: [[Script:ChatSetAttr#Add_new_thing_to_Repeating_Section|Adding a new magic item to a sheet]], with one chat command <br />
* '''[[Script:Ammo]]''' can be used for updating ammo & spellslots when used<br />
<br />
==Utilizing the ''5th Edition OGL by Roll20 Companion'' API Script==<br />
'''{{repo|Roll20/roll20-api-scripts/tree/master/5th%20Edition%20OGL%20by%20Roll20%20Companion 5th Edition OGL Companion}}'''is an official companion script for the "D&D 5E by Roll20" character sheet. The Companion currently supports Ammo Tracking, Automatic NPC Tokens, Automatic Death Save Tracking, and Automatic Spell Slot Tracking. <br />
<br />
{{mbox | text = Installing & creating [[API]] Scripts is a {{Pro}} feature. In order to be able to access these advanced scripts, the [[GM]] of the campaign must be a [[Pro]] subscriber and enable it for their campaign.}}<br />
<br />
<br />
'''''How to Add the API Script to your Game'''''<br />
<br />
If you have a PRO account, you can install the API script by going to your game's Campaign Page and clicking on the '''Settings''' button, and then choosing '''API Scripts'''. This brings you to the API Scripts page for your current game. The Companion Script is part of the One-Click Community API Installation options. Under the Script Library tab, there is a drop down menu that lists all the available community created scripts. Scroll down till you find the '''System Toolbox''' category and select the "5th Edition OGL by Roll20 Companion" script. The version number, the script's author, and a brief description of what the script does will appear right below the drop down menu once it is selected. Below that, click on the blue "Add Script" button to add the script to your game.<br />
<br />
<br />
'''''List of API commands for the 5th Edition OGL Companion API Script'''''<br />
* <code>!5ehelp</code> - Gives a list of the script's API commands in the chat tab.<br />
* <code>!5estatus</code> - Lists the current status of the script's features in the chat tab.<br />
* <code>!ammotracking on/off/quiet</code> - Automatically expends linked resource when attack is made<br />
* <code>!autonpctoken on/off</code> - Automatically generates a NPC token on the GM's screen based on the default token when an NPC's health calculation is rolled<br />
* <code>!deathsavetracking on/off/quiet</code> - Automatically ticks off successes and failures when death saves are rolled, clearing on death, stabilization, or hp recovery<br />
* <code>!longrest <character name></code> - This will add Hit Dice recover and if spelltracking is on, this command will reset all of the character's spell slots to unspent.<br />
* <code>!npchp <character name></code> - Rolls NPC hit point totals using their formula and updates the token bar. If no character name is provided it will roll the selected tokens.<br />
* <code>!spelltracking on/off/quiet</code> - Automatically expends spell charges as cast, factoring in higher level casting, and spells marked as Rituals will not spend a spell slot.<br />
<br />
<br />
Options:<br />
* ''on'' - Toggles the functionality on (default)<br />
* ''off'' - Disables the functionality<br />
* ''quiet'' - Maintains functionality while preventing results from being output to the chat.<br />
<br />
<br />
===Automatic Ammunition Tracking===<br />
''Main Article:'' '''[[D&D 5E by Roll20: How to setup Ammunition and Resource tracker]]'''<br />
<br />
Automatic Ammunition Track is a feature that requires the above Companion API Script. Once installed, follow these instructions to enable automatic ammunition tracking in your game:<br />
<br />
This example sets up a Longbow with a quiver of Arrows to track.<br />
# On the Settings (Gear Icon) tab of a character sheet, under GENERAL OPTIONS, make sure that the INVENTORY option is set to "Compendium Compatible" and not "Simple".<br />
# While still under GENERAL OPTIONS, set the AMMO TRACKING feature to ON.<br />
# Create manually or drag a missile weapon (ex. Longbow) from the Compendium to your sheet.<br />
# Create manually or drag a missile type (Arrows) from the compendium to your sheet<br />
# Expand the missile type (Arrows) by clicking on the "I" information icon that appears when hovering the mouse over the item.<br />
# Select the USE AS RESOURCE checkbox. (ammunition items dragged from the Compendium will have this option automatically checked off)<br />
# On the CORE tab, expand the missile weapon (Long Bow) in the ATTACKS & SPELLCASTING section by clicking on the gear icon that appears when hovering over the attack.<br />
# In the AMMUNITION section put the exact name of the ammunition resource (Arrows). If you want to spend more than one piece of ammunition per shot you want to add the number of pieces after the name of the ammunition resource and a comma. (ex. ''Arrows,2'' )<br />
<br />
<br />
Now, any time the missile weapon (Longbow) is rolled, a piece of ammunition will automatically be spent and the chat will make note. Additionally after the first time the missile weapon is used the AMMUNITION section will update with the ID of the resource repeating section, this is normal and expected.<br />
<br />
<br />
===Automatic Spell Slot Tracking===<br />
<br />
Automatic Spell Slot Tracking is a feature that requires the above Companion API Script. Once installed, follow these instructions to enable automatic spell slot tracking in your game:<br />
* In the chat input area of the Sidebar, type ''!5estatus'' and press Enter, to check if spelltracking is set to 'on'.<br />
* If not, type ''!spelltracking on'' and press Enter to activate this feature.<br />
* Alternatively, you may type ''!spelltracking quiet'' and press Enter to activate this feature, while preventing spelltracking messages from being displayed in the chat.<br />
<br />
<br />
<br />
Once the Spell Slot Tracking has been activated, each time a spell is cast:<br />
# The number of cast spells of the appropriate level is updated in the Spell tab of the character sheet (see [[5th Edition OGL by Roll20|Spell Levels & Spells Per Day]]).<br />
# A message is output in the chat, displaying the spell level, the number of available spell slots and the number of used spell slots for this level.<br />
# Spell slots decrement as spells are cast. <br />
# Spells that are marked as a Ritual do not affect the tally of spell slots when cast.<br />
<br />
<br />
At any time, you can manually adjust this count directly in the Spell Page of the character sheet.<br />
<br />
=Updates=<br />
* {{hc|articles/360037772613-Change-Log Roll20 Changelog}} - Full Changelog of Roll20, updates for 5E sheet are included<br />
* {{fpl|10096810/ D&D 5th Edition by Roll20 (Q2Y2021)}} often has mentions of latest updates<br />
* Major Sheet Updates:<br />
** Feats can now be selected in Charactermancer {{fpl|8891809 June 2020}}<br />
** Game [[creator]] can select which [[compendiums]] are or aren't accessible in a game. [https://app.roll20.net/forum/post/8738570/release-note-for-may-26-2020 May 26 2020]<br />
<br />
=Known Issues=<br />
The sheet has a number of known bugs and issues, some which are mentioned in the sheet's latest forum thread.<br />
<br />
'''Charactermancer/Character Creation'''<br />
* '''Charactermancer & Compendium drag-n-drop doesn't work when sheet is in a separate window.''' This is [[Character_Sheets#Character_Sheet_in_a_separate_window|an inherit limitation to how character sheets work]] at the moment. <br />
* '''Multiclassing & spell selection''' - There are troubles when multiclassing spellcasters and getting to select spells from the right lists.<br />
* '''Duplicate races/classes from Essential Kit appear in selection''' You need to uncheck EK from your compendium for it to no longer appear in selections.<br />
<br />
<br />
'''General:'''<br />
* '''Warlock spell slots''' - The Warlock's spell slots don't work too well with the sheet, and most people use some manual adjustments for how they work. The number of spell slots also appears wrong in the Charactermancer.<br />
* '''NPC stat <code>desc</code> changed into <code>description</code>''' This was a recent update that broke some macros for people, resulting in error messages along: "can't find ''desc'' attribute" {{fpl|8297517/ release notes march 2020}}<br />
<br />
=Sheet Guides=<br />
* [[5E Macros]]<br />
* {{blog|638339117446578176/tome-of-tips-dungeons-dragons-5th-edition-ogl Tome Of Tips: The D&D 5E character sheet}}<br />
* {{yt.be|9BGGr97qJdY|Learning Roll20: EP01 Character Sheets (D&D 5E)}} 50min, by Roll20 (2020)<br />
<br />
=Related Pages=<br />
* D&D 5E by Roll20 sheet<br />
** [[D&D5E by Roll20 NPC Attributes]]<br />
** [[D&D 5e by Roll20 Roll Templates]]<br />
** [[D&D 5E by Roll20: How to setup Ammunition and Resource tracker]]<br />
* [[5E]] - general D&D 5E info for Roll20. Lists also the alterantive character sheets for 5E<br />
* [[D&D]] - Roll20 stuff on the various editions.<br />
* {{Compendium}}<br />
** [[Compendium Sharing]]<br />
* [[Character Vault]]<br />
<br />
=See Also=<br />
* {{repo|Roll20/roll20-character-sheets/tree/master/DD5thEditionLegacy Sheet sourcecode}} - (Public version of sheet code is 1½+ years behind from what is actually used)<br />
* {{hc|articles/360037772613-Change-Log Roll20 Changelog}} - Full Changelog of Roll20, updates for 5E sheet are included<br />
<br /><br />
<br /><br />
[[Category:Character Sheet Documentation]]<br />
[[Category:Official Sheet]]<br />
[[Category:DnD5E]]<br />
[[Category:Featured articles]]</div>5004103https://wiki.roll20.net/D%26D_5E_by_Roll20D&D 5E by Roll202021-10-01T16:24:32Z<p>5004103: /* Directly Referencing Attributes */</p>
<hr />
<div>{{revdate}}{{HCbox|{{hc|360037773573-5th-Edition-OGL-by-Roll20 D&D 5E by Roll20}} }}<br />
[[File:5E OGL Sheet Core v2.6.png|500px|thumb|right|The '''D&D 5E by Roll20''' Character Sheet]]<br />
<br />
This is the community-driven documentation for the '''[[5E|D&D 5E]] by Roll20''' character sheet. Previously the sheet was known as the '''"5th Edition OGL Sheet"''' or just the '''"OGL Sheet"'''.<br />
<br />
=The Basics=<br />
This page is a ''[[Community Wiki]]'' guide to the Official D&D 5th Edition character sheet, which is updated with info tricks that might not be covered by the {{hc|articles/360037773573-5th-Edition-OGL-by-Roll20 official sheet documentation}}.<br />
<br />
<br />
To find out about the latest updates, issues and talk about the sheet, check the {{fpl|10096810/ D&D 5th Edition by Roll20 (Q2Y2021)}}-thread on the {{forum|category/277980 forums}}.<br />
<br />
<br />
[[Bug|Bug reports]] for the sheet is best reported in the same thread. If you find bugs in the 5E Compendium or 5E marketplace content, {{bug}}.<br />
<br />
<br />
__TOC__<br />
<br />
==Adding the Character Sheet to a Game==<br />
[[File:D&D5E-Roll20-sheet-selection.png|300px|thumb|right|The Sheet Selection Menu]]An official or community contributed character sheet [[Add_character_sheet#Adding_a_Character_Sheet_to_your_Campaign|can be added to any game when you first create it]]. On the Game Creation screen, underneath the large blue '''“I’m Ready, Create Game!”''' button, is the '''“Optional: Choose a Character Sheet”''' section. Located here is a drop down menu that lists all the character sheets built either by Roll20 officially or created by the community. These sheets are sorted under their respective RPG Systems in alphanumerical order. Once selected, a preview of the character sheet will load upon the creation page for you to review as well as showcase relevant information about the sheet, such as the sheet’s creator and its key features.<br />
<br />
<br />
The '''D&D 5E by Roll20''' Sheet can be found under either: '''Sheets by Roll20''' → D&D 5E by Roll20 OR '''Dungeons and Dragons 5E''' → D&D 5E by Roll20<br />
<br />
<br />
If you want to add a character sheet to an existing campaign, you can find this drop down menu once again by accessing the [[Game Settings Page]] from the [[Game_Management#Game_Details_Page|Game Details]]-page.<br />
<br />
{{mbox | text = '''NOTE:''' If you have added custom attributes to your character journals prior to adding a character sheet to a campaign, you may want to delete them first. Adding a character sheet to a campaign will create its own set of custom attributes on all of your character journals, but it will reuse any attributes encountered if they share the same name. This can cause calculation issues on the sheet.}}<br />
<br />
<br />
If you were previously using either the [[DnD5e Shaped Character Sheet|D&D 5E (Shaped)]] or [[DnD5E_Community_Contributed|D&D 5E (Community Contributed)]] sheets and wish to transfer over to the '''D&D 5E by Roll20''' version, it's a good idea to ask help on the [https://app.roll20.net/forum/category/277980 forums].<br />
<br />
<div style="clear: both"></div><br />
<br />
==Where to Find the Sheet==<br />
Once a character sheet has been added to a game, and once inside it, on all [[Journal#Characters|Characters Journals]], a new tab will be available between the '''“Bio & Info”''' and '''“Attributes & Abilities”''' tab labelled '''“Character Sheet”'''. Much like the Attributes & Abilities tab, only players who have been granted Edit permissions for the journal entry will be able to access the Character Sheet tab.<br />
<br />
''See also:'' '''[[Add_character_sheet#Adding_New_Characters_In-Game|Create new character sheets to your players]]'''<br />
<br />
==Sheet Features==<br />
The '''D&D 5E by Roll20''' sheet has all of the functionality of a pen and paper character sheet, and much more. Certain aspects of the sheet have been streamlined or automated to remove bookkeeping and speed up gameplay. The key features are auto-calculations, [[Macro|macro]] buttons, and [[D&D 5e by Roll20 Roll Templates|roll templates]]. The sheet defaults to using the rules as printed in the D&D 5E SRD, however it's dynamic enough to allow you and your group to use many custom house rules you might want.<br />
<br />
===Auto Calculations===<br />
Many parts of the sheet use auto calculations to fill in derived attributes with the expectation that you're using the rules as printed in the 5th Edition SRD. Many of these calculated traits can be modified from the character sheet's <span style="font-family:Pictos;">y</span> [[D&D 5E by Roll20#Settings Page|Settings]]-tab, and those set by Sheet Workers can be edited directly. Below are some examples of Sheet Worker and Auto Calculation functionality:<br />
<br />
* '''Class''' - Changing the character's class from the header will automatically update the character's saving throw proficiencies, their hit die type, spell casting ability, and spell save DC. <br />
* '''Level''' - Changing the character's level will also update their proficiency bonus, number of spells per day, and more.<br />
* '''Attributes''' - Changing one of the character's attributes will also update the related modifier, skills that are based on that attribute, and derived stats such as initiative or passive perception.<br />
<br />
===Roll Buttons and Roll Templates===<br />
[[File:5E_OGL_Sheet_Rollable_Buttons.gif|right|frame|Any label that highlights in red when the mouse hovers over it is rollable.]]<br />
''Main Page:'' '''[[D&D 5e by Roll20 Roll Templates|D&D 5E by Roll20 Roll templates]]'''<br />
<br />
Most of the stats in the game can be rolled by hovering over their name, the stat will turn red, and then left-clicking the mouse. This is true for Attributes, Saves, Skills, Hit Dice, Death Saves, Tool Proficiencies, Attacks & Spellcasting, Spell Cards, and NPC Actions/Attacks. Any of these roll buttons can be dragged directly from the sheet to your [[Macro Quick Bar]], enabled from the <span style="font-family:Pictos;">y</span> [[My Settings]]-tab of Roll20's [[Sidebar]].<br />
<br />
Player characters have both a simple and attack [[D&D 5e by Roll20 Roll Templates|roll template]] that is output to the {{Text Chat}}-tab on the right hand [[Sidebar]]. The simple template is used for everything except for attacks. The attack template is shaped to show up in three pieces; the attack at the top, information in the middle, and damage at the bottom. Depending on your sheet settings, the damage will not roll automatically unless you click on the name of the attack from the roll template in the chat tab. This was designed to simulate the tabletop experience of rolling to attack and then rolling damage if necessary. You can change this behavior in the sheet <span style="font-family:Pictos;">y</span> [[D&D 5E by Roll20#Settings Page|Settings]]-tab, tab under "Auto Damage Roll".<br />
<br />
<div style="clear: both"></div><br />
<br />
====Rolling for Advantage and Disadvantage====<br />
With the '''D&D 5E by Roll20''' Sheet, the [[D&D 5E by Roll20#Settings Page|default sheet settings]] has Advantage set to ''always'' rolled for convenience purposes. It is commonly agreed upon that a gaming group uses the left roll result when advantage is not being used for a check. When advantage or disadvantage is in play, simply choose the higher or lower result among the two per usual. You can change this behavior in the sheet <span style="font-family:Pictos;">y</span> [[D&D 5E by Roll20#Settings Page|Settings]]-tab (gear icon at the top right of the page), tab under "Roll Queries". You have the choice of "Always Roll Advantage" (the default setting), "Advantage Toggle", "Query Advantage", or "Never Roll Advantage".<br />
<br />
'''Advantage Toggle:''' The Advantage Toggle will add three buttons to the top of your character sheet: "Advantage", "Normal", and "Disadvantage". You can click on any of these to roll for Advantage (the highest roll result will highlight in black), Disadvantage (the lowest roll result will highlight in black), or a single d20.<br />
<br />
'''Query Advantage:''' The Query Advantage setting will prompt a dialog box to appear whenever you roll from your sheet. It will ask you to select what sort of roll want to do (Normal, Advantage, Disadvantage). After choosing the type you want, the roll will occur in chat.<br />
<br />
'''Never Roll Advantage:''' When rolling from your sheet, only a single d20 will be rolled.<br />
<br />
===Resizable Text Fields===<br />
[[File:5E_OGL_Sheet_Resizable_Text_Fields.gif|right|frame|Making a text field larger is just a matter of click and dragging.]]There are many free-text fields on the sheet that give you a place to keep information that doesn't necessarily follow a specific format. All of the fields on the Bio Tab are free-text fields as well as the Description fields present for attacks, spells, equipment, features & traits, and NPC actions. If your text overflows past the bottom of a text field, you can resize it to view the content in its entirety by clicking and dragging the bottom right corner icon shown in the adjoining image.<br />
<br />
<br />
At present, these fields can only contain raw text. There are no formatting options (bold, italic, etc.) available.<br />
<br />
<div style="clear: both"></div><br />
<br />
===The Padlock Button and Organizing Elements===<br />
(aka. '''[[Character_Sheets#Repeating_Section|Repeating Section]]''')<br />
[[File:5E_OGL_Sheet_Padlock.gif|right|frame|The Padlock Toggle]]There is a <span style="font-family:Pictos;">(</span> (padlock) icon set at the bottom of several different fields of the '''D&D 5E by Roll20''' Sheet. It is used where a player is meant to add entries such as individual attacks, actions, pieces of equipment, features & traits, tool proficiences & custom skills, other proficiencies & languages, and spells. This icon behaves as a toggle button. <br />
<br />
When set in the <span style="font-family:Pictos;">(</span> locked position (default), a player can add new entries into the field. When the button is toggled to <span style="font-family:Pictos;">)</span>(unlocked), a player can no longer add new entries, but they will be able to reorder or delete any of the existing ones. The <span style="font-family:Pictos;">#</span>(red trash bin)-icon overlaid on the right hand side of the entry will delete it.<br />
<br />
{{Ambox<br />
|nocat=true<br />
| type = content<br />
| text = '''Deleting an entry cannot be undone!''' On left side of every entry while the padlock is <span style="font-family:Pictos;">)</span> unlocked is a re-sort icon symbolized by '''<big>≡</big>'''(three parallel lines). By clicking and dragging on this icon, you can rearrange the order of the entries in the field.<br />
}}<br />
<br />
{{Ambox<br />
|nocat=true<br />
| type = content<br />
| text = Some of the features of '''Repeating Sections''' do not work when the [[Character_Sheets#Character_Sheet_in_a_separate_window|Character Sheet is in a separate window]].<br />
}}<br />
<br />
<br />
<div style="clear: both"></div><br />
<br />
==Utilizing the 5th Edition SRD Compendium==<br />
[[File:5E_OGL_Sheet_Compendium.png|right|The Compendium Tab]]Upon adding the D&D 5E by Roll20 Character Sheet to a campaign, the [https://app.roll20.net/compendium/dnd5e/BookIndex| 5th Edition SRD Compendium] is automatically enabled for use from it's own <span style="font-family:Pictos;">i</span> [[Compendium]]-tab in the '''[[Sidebar]]''' of the application. It's located between the {{Journal}} and <span style="font-family:Pictos Custom;">u</span> [[Jukebox]]-tabs, and is accessible for both GM and Player alike.<br />
<br />
<br />
The <span style="font-family:Pictos;">i</span> [[Compendium]] allows for rapid searching of all rules, classes, monsters, spells, items, and more that are included in the 5th Edition SRD. This minimizes time spent for the gaming group to leaf through a book in the middle of a session for a rule clarification. Even better, both the GM and the Player can utilize dragging and dropping* from the <span style="font-family:Pictos;">i</span> [[Compendium]]-tab directly to your character sheets. This makes statting NPCs and PCs far faster than inputing everything manually.<br />
<br />
{{mbox | text = '''NOTE:''' The 5th Edition SRD is similar but NOT identical to the ''Dungeons and Dragons'' 5th Edition Rule Book. Some skills, classes, creatures, items, and other elements found within the ''Dungeons and Dragons'' rule book are strictly intellectual property of Wizards of the Coast and not accessible through their Open-Game License(OGL).}}<br />
<br />
<br />
===Statting PCs===<br />
Dragging from the <span style="font-family:Pictos;">i</span> [[Compendium]] works for the Equipment and Spell fields of the PC Sheet. This will not only carry over the name of the item or spell, but the relevant attack and damage rolls and any rules or flavor text that comes with it. Adding Compendium items in this fashion also automatically adds the equipment item (if it's a weapon) or spell to the Attacks & Spellcasting field to roll directly from. Items that modify a character's Attributes, Saves, AC, To Hit, Damage, Spell Attacks, and Spell DC will be automatically calculated on the sheet when dragged in. For example, if a Belt of Giant Strength is dragged to a sheet, the strength Attribute Score will become highlighted in blue and its attribute score will be increased. An asterisk is appended to the right of the score to also signify that it has been modified by an item. When you mouse over this number, the strength Attribute Score will revert back to what its unmodified total so you can refer back to it. Dropping a Compendium items that is an ammunition type (arrows, crossbow bolts, blowgun darts, etc) will automatically fill out a resource field for that item and link it to its entry in the Equipment section.<br />
<br />
To insert a Compendium item into the character sheet, run a search for the Item or Spell you want to add in the <span style="font-family:Pictos;">i</span> [[Compendium]]-tab. Once found, click and drag on the Compendium item's name so that it creates a little named tile that follows along with your mouse. Drag this over to the character sheet, it doesn't matter where. A text box that reads, "ACCEPTING DROP FROM COMPENDIUM" will appear on your sheet if this is done correctly. Let go of the tile and the entry will be auto-completed with all the data pertaining to the the Compendium entry in the correct location on the sheet. You can see this in action below under [[#Equipment|Equipment]].<br />
<br />
===Statting NPCs===<br />
You can fill out an entire NPC sheet in a single drag and drop. Run a search for the NPC you want to create from the <span style="font-family:Pictos;">i</span> [[Compendium]]-tab. Once found, click and drag on the NPC name so that it creates a little named tile that follows along with your mouse. Drag this to anywhere over the Tabletop area of the screen. Let go of the tile and a new character journal will be created named after the NPC from the Compendium entry. Its sheet will be changed over to the NPC sheet and filled with the entire NPC entry from the Compendium including their Actions, Reactions, and Legendary Actions if applicable. If you're using one of the Compendium expansions bought from the Roll20 Marketplace like the Monster Manual or Volo's Guide to Monsters, token art will also be pulled from the Compendium entry, placed on the table, and linked to your NPC's journal.<br />
<br />
You can also drag an NPC entry from the Compendium to an existing journal entry if you have the sheet open. If the sheet is in PC sheet mode, it will automatically change it over to the NPC sheet, and add its entry elements to it.<br />
<br />
One thing to note about dragging a stat block over from the Compendium is that it uses an ''additive'' behavior. It will not replace anything that you have already entered manually.<br />
<br />
=The PC Sheet=<br />
The '''D&D 5E by Roll20 Sheet''' contains both the PC Sheet ''and'' the NPC Sheet. By default, a new character journal is set to the PC sheet, but you can switch between the two by toggling it from the [[#Settings Page|General Options Settings]]. The PC Sheet is split up into four pages and can be selected from the buttons just underneath the header at the top of the sheet. They are listed from left to right order: The [[#Core Page|Core Page]], The [[#Bio Page|Bio Page]], The [[#Spells Page|Spells Page]], and The [[#Setting Page|Setting Page]].<br />
<br />
== Creating and Leveling up a character with Charactermancer ==<br />
Players and GMs using the '''D&D 5E by Roll20''' Sheet can use the Charactermancer to create and level up characters.<br />
<br />
'''How to use the Charactermancer for [[Charactermancer (D&D Fifth Edition)|character creation and leveling]].'''<br />
<br />
<br />
{{Ambox<br />
|nocat=true<br />
| type = content<br />
| text = The Charactermancer do not work when the [[Character_Sheets#Character_Sheet_in_a_separate_window|Character Sheet is in a separate window]].<br />
}}<br />
<br />
==Core Page==<br />
[[File:5E_OGL_PC_Core_Guide.jpg|right|frame|The Core Page]]The Core Page is selected by default and has most of the information you'll want to use on a regular basis to play your character. This should look very similar to the content you would normally find on the first sheet of the physical "D&D 5E by Roll20" player character sheet. The screenshot at the top of this wiki page displays the entirety of the Core Page. <br />
===(1) Core Header===<br />
[[File:D&D5E-Roll20-core-header.png|550px]]<br />
<br />
The header block at the top of the sheet changes based on the page you have selected. On the Core page you can select a class by its dropdown menu. The available options from the dropdown are: Barbarian, Bard, Cleric, Druid, Fighter, Monk, Paladin, Ranger, Rogue, Sorcerer, Warlock, and Wizard. You can create a custom class from the Settings Page.<br />
<br />
Once a class has been selected you can update the class's level by changing the number next to the class. The sheet will also automatically mark the abilities that class has proficiency in as well as automatically select the dice that will be used when Hit Dice are rolled. You can change the Hit Dice setting manually from the options menu. If your character multi-classes, then the secondary class and its level will appear beside the primary class. This Class and Level field can hold up to four classes if desired.<br />
<br />
The fields for Background, Race, Alignment, and Experience Points allow you to fill in whatever text you wish to put in them. The Character Name persists over all pages of the sheet and is tied to the name you give to the journal entry. Changing it on the sheet itself will also change the name on the character journal and vice versa once it is closed.<br />
<br />
===(2) Attributes===<br />
<br />
[[File:5E_OGL_Sheet_Attribute_Block.jpg|left]]Along the left side of the sheet are listed the 6 primary attributes: Strength, Dexterity, Constitution, Intelligence, Wisdom, and Charisma. These attributes are used by almost every other calculation on the sheet, as they are the core definition of a character. Each attribute block has the core attribute score, which can be changed by modifying the number in the oval at the bottom of each block, and, inside the square, the attribute modifier which is auto-calculated based on the score below it. All racial ability score increases must be manually added to the core attribute score using the settings "gear" symbol at the top of the page (where the Core, Bio, and Spells buttons are located.) The attribute modifier uses the following calculation to set the value:<br />
<br />
<br />
<code>[[floor((@{strength}-10)/2)]]</code><br />
<br />
The attribute can be referenced by its name, such as @{dexterity} while the attributes modifier can be referenced by adding the mod suffix, @{dexterity_mod}.<br />
<br />
<div style="clear: both"></div><br />
<br />
===(3) Inspiration===<br />
<br />
[[File:D&D5E-Roll20-inspiration.png|left]]You can track whether or not you have Inspiration by clicking the circle next to the Inspiration block at the top left of the Core page. This will toggle a dragon spiral icon on and off for indication purposes.<br />
<br />
<div style="clear: both"></div><br />
<br />
===(4) Proficiency Bonus===<br />
<br />
[[File:5E_OGL_Sheet_Proficiency.png|left]]Your character's proficiency bonus is listed near the top left of the page. You cannot modify this value manually, instead it is automatically set based off your character's over-all level. Your character's Level can be set by changing the number next to your Class name in the [[#header_info|Header]] at the top when on the Core page.<br />
<br />
<div style="clear: both"></div><br />
<br />
===(5) Saving Throws===<br />
<br />
[[File:5E_OGL_Sheet_Saving_Throws.png|left]]Next to the core Attributes on the left side of the page is a list of the same attributes to be used in making saving throws. To mark an attribute that your character has proficiency in for saving throws, check the box next to the appropriate attributes. When you select a class in the header section of the Core page it will automatically check the correct boxes for that class's proficiencies.<br />
<br />
You can add an additional field to Saving Throws to serve as a Global Save Modifier. An example is if the character is under the influence of the Bless spell and can roll a 1d4 in addition to the result of their saving throws. This is enabled from the Settings Page under General Options. Once enabled a seventh checkbox and field will be added at the bottom of the Saving Throws block with a text field to enter the additional die roll. For this example, you could enter "1d4[BLESS]" in the global checkbox's text field that you can enable when the character is under the effects of the Bless spell. The word between the brackets becomes a label that can be seen when you mouse over the roll result in chat. While this Global Save Modifier is checked, every roll made from the Saving Throws block and performing a Death Save will add this modifier to the result.<br />
<br />
<div style="clear: both"></div><br />
<br />
===(6) Skills===<br />
[[File:5E_OGL_Sheet_Skills.png|left]]<br />
To the right of the Core Attributes is a list of all of the character's Skills. Each skill can be rolled by clicking on the skill name. If you have proficiency in a specific skill, then you would check the box next to the skill name, this will automatically add your proficiency bonus to that skill's checks. Each skill also lists the core attribute, that is used in the roll calculations, next to it in parenthesis.<br />
<br />
You can set advanced skill options for the Settings page, such as skill expertise, flat bonuses from class archetypes or feats, as well as Jack of All Trades.<br />
<br />
<div style="clear: both"></div><br />
<br />
===(7) Armor Class, Initiative, & Speed===<br />
<br />
[[File:D&D5E-Roll20-AC-Init-Speed.png|left]]The Armor Class & Speed blocks at the top center of the page can be used to keep track of your Armor and Speed values. The Initiative block cannot be modified manually, but instead is auto-calculated based off your character's Dexterity. If you have any additional initiative modifiers you can add them on the {{gear}} [[#Settings Page|Settings Page]] under Initiative Modifier in the Class Options block.<br />
<br />
Armor Class can also be tracked automatically by using the [https://app.roll20.net/compendium/dnd5e/BookIndex Compendium] compatible inventory, on by default.<br />
<br />
You can configure a custom AC calculation using the {{gear}} [[#Settings Page|Settings Page]] under the Attribute Tracking section. It's listed as "Armor Class Tracking" and is set to "Automatic" by default. If you select Custom, you can select up to two different attributes to apply to the character's armor class.<br />
<div style="clear: both"></div><br />
<br />
====Using the Global AC Modifiers====<br />
If you check the "Show Global AC Modifier" field in the character sheet General Options settings, the sheet will display a repeating section to configure and apply different modifiers to AC. So, for example, if your character has a common bonus, such as from a spell or a conditional feat or fighting style, you can toggle that AC bonus from the character sheet directly.<br />
<br />
====Rolling for Initiative and the Turn Order Tracker====<br />
Clicking on the word INITIATIVE will roll that character's initiative score. If your players have [[Token|tokens]] linked to their character sheets, they can roll their initiative ''and'' simultaneously add their character and its initiative score to the {{Turn Tracker}} automatically. What is required of the player is that their linked token must be currently selected on the Tabletop before they roll off their sheet.<br />
<br />
If you would like to enable a tie breaker component to Initiative, there is an option to enable this from the [[#Settings Page|Settings Page]] under the "Attribute Options" block. What this does is that it will add your dexterity Attribute Score as a decimal value to your Initiative. So if you have a character with a dexterity attribute score of 14, your initiative modifier will change from a <code>2</code> to a <code>2.14</code>.<br />
<br />
===(8) Hit Points & Temporary Hit Points===<br />
[[File:5E_OGL_Sheet_HP.png|left]]The Current Hit Points and Temporary Hit Points blocks are used to keep track of your character's Hit Points (HP). Inside the Current Hit Points block, at the top, is a line that lists the character's maximum amount of HP. <br />
<br />
<br />
When your character takes damage, if they have any, it should be subtracted from their Temporary Hit Points first, then any remaining damage would then come off of the character's Current Hit Points.<br />
<br />
<div style="clear: both"></div><br />
<br />
===(9) Hit Dice===<br />
[[File:5E_OGL_Sheet_Hit_Dice2.png|left]] The Hit Dice block is used to keep track of and roll your character's hit dice. Inside the Hit Dice block, at the top, is a line to keep track of the total number of dice your character can have. In the main area of the block you would keep track of the remaining hit dice. Clicking the "HIT DICE" label will roll the hit dice for your selected class automatically. If you wish to change the dice that is rolled you can do so in the Class Options section of the [[#Settings Page|Settings Page]] ({{gear}} icon). <br />
<br />
<br />
If your character is multi-classed, when rolling your hit dice (by clicking "''HIT DICE''", a pop-up will ask which of your character's current class's hit dice you want to roll. This input accepts only numerals a input to make automatic tracking of the [[API:A Guide to the API|API]] possible.<br />
<div style="clear: both"></div><br />
<br />
===(10) Death Saves===<br />
[[File:5E_OGL_Sheet_Death_Saves.png|left]]The Death Saves block is used to keep track of your character's death save rolls once they have been knocked out. You can click the "DEATH SAVES" label to make a death save roll. If you roll greater than 10 you would check one of the boxes next to "Successes" otherwise you would check a box next to "Failures". If your character has any modifiers to their death save rolls they can be added in the Class Options section of the Settings Page(gear icon).<br />
<div style="clear: both"></div><br />
<br />
===(11) Attacks & Spellcasting===<br />
[[File:5E_OGL_Sheet_Attacks_And_Spellcasting.png|left]]The Attacks & Spellcasting block in the center of the Core page of this character sheet will be one of the most often used sections. To start, you can manually add any attack or spell to this section by hovering over the block and clicking the "Add" button(the <span style="font-family:Pictos;">&</span> symbol). This will open a form that can be filled out with all of the information about the specific attack or spell you are adding. <br />
<br />
<br />
This section will automatically add attacks, with all the stats, for spells that have an attack component when they are added to your spell sheet on the [[#Spells Page|Spells Page]]. This happen both if you add the spell manually or if you drag and drop a spell from the <span style="font-family:Pictos;">i</span> [[Compendium]]. An attack is also automatically created if you drag and drop an item from the Compendium into your sheet.<br />
<br />
<div style="clear: both"></div><br />
[[File:Poisoned Dagger 5e Attack.png|right|frame|An example of an attack form filled out for a physical attack using a +1 Poisoned Dagger]]For example, lets say Erin the Bold has a +1 Poisoned Dagger that has the stats of a regular dagger, but also metes out an additional 1d6 of poison damage alongside the typical 1d4 points of piercing damage. The image displayed to the right is how the attack would be set up:<br />
<br />
<br />
Since this is a [https://app.roll20.net/compendium/dnd5e/Items:Dagger#h-Dagger dagger], and daggers have the "[https://app.roll20.net/compendium/dnd5e/Weapons#h-Weapons Finesse]" attribute I can chose either STR or DEX for my bonus attribute. Erin is quicker than she is strong, so we will pick DEX as the attribute to attack with, as well as checking the "proficient" checkbox since Erin is experienced with using these sorts of weapons. She doesn't have any other gear that might make her attacks better, so we will leave the generic bonus between the attribute and proficiency blank, or 0. Being a +1 Poisoned Dagger means that it is also magical, so it gets a 1 in the magic bonus slot just below. A dagger can also be used as a thrown weapon, so we've added the weapon's throwing range info to the "Range" field. Since a weapon does damage, we have checked the first "Damage" checkbox and filled in the required fields. This dagger does 1d4 piercing damage + Erin's DEX mod + 0 bonus damage (this would be used for bonus damage on top of the magical +1) and it doesn't have anything to change the critical damage so we just put the same damage into the "crit" box. Because this dagger can also cause poison damage, we also check the second "Damage" checkbox and fill in the info for the 2nd set of damage. The poison does a flat 1d6 poison with no extra bonuses, so we've selected "-" to say there is no attribute that adds to this damage. This damage also doesn't have anything to make the crit different so we set that to 1d6 as well. There are no extra saving throws or effects that are included with this attack, so we leave these additional sections blank. <br />
<br />
These additional effect sections will be used more commonly with spells, like [https://app.roll20.net/compendium/dnd5e/Fireball#h-Fireball Fireball], where you would require a DEX save against your SPELL DC, which will be set according to your character's spell casting level. For a fireball, the save effect would be "half damage" and the "Description" would be something like "Hits all creatures within 20 ft of the explosion point".<br />
<br />
After you are done modifying all of individual stats for an attack you can click the gear icon at the top right of that section and it will hide the stats for that attack. If ever you need to change these stats in the future you can hover over the entry and click the <span style="font-family:Pictos;">y</span>(gear)-icon that shows up to unhide the stats section. <br />
<br />
<div style="clear: both"></div><br />
====Adding Global Attack and Damage Modifier====<br />
You can add two special entries to the Attacks & Spellcasting block to handle to global Attacks and Damage modifications to rolls. An example is if the character is under the influence of the Bless spell and can roll a 1d4 in addition to the result of their attack roll. This is enabled from the [[#Settings Page|Settings Page]] under General Options. Once enabled, a checkbox will be added at the bottom of the Attacks & Spellcasting block with a text field to enter the additional die roll. For this example, you could enter <nowiki>"1d4[BLESS]"</nowiki> in the global checkbox's text field that you can enable when the character is under the effects of the Bless spell. The word between the brackets becomes a label that can be seen when you mouse over the roll result in chat. While these Global Modifiers are checked, every roll made from the Attacks & Spellcasting block will add these modifiers to the result.<br />
<br />
====Rolling from the Attacks & Spellcasting Block====<br />
[[File:Poisoned Dagger 5e Roll.png|frame|An attack roll from a +1 Poisoned Dagger]]Rolling from the Attacks & Spellcasting Block is no different than rolling from any other portions of the character sheet. Hovering your mouse over any entry here will highlight its entire label (NAME, ATK, and DAMAGE/TYPE) in red and you'll be able to click on it to roll the attack or spell. You can also drag this entry into the Macro Bar to give yourself easy access to this attack. Because this is a repeating section, the macro name will be a bit messy, but you can right-click the button and rename the macro to whatever you like.<br />
<br />
With any attack that checks for AC, you will see TWO rolls set side by side for the Armor Class check with the name of the attack listed underneath them with the Attack modifier bonus (ATK) appended to the Attack name in light grey. The Roll20 D&D 5E Character Sheet ''always'' rolls for Advantage by default, so you will always have two roll results for this check (most gaming groups use the left roll result if neither Advantage or Disadvantage is being factored in the check). If there is a specified range for the attack, this will be listed above the attack's name.<br />
<br />
Underneath the AC Check and Attack Name is the Damage roll result for the attack. Underneath this roll result will be the Damage Type (ex. slashing, piercing, poison, fire, etc.) listed in light grey italicized font.<br />
<br />
For spells that don't check for AC and instead require a Saving Throws to mitigate or negate the spell's effect, the SPELL DC is listed first. Underneath this, in italicized font, is the effect if a character succeeds the check listed. Underneath the effect is the required attribute saving throw that must be rolled. If Damage is applied, this result is rolled and listed next with its Damage Type.<br />
<br />
[[File:5e_attack_example.gif|right|frame|How to view attack damage when the sheet is set to "Don't Auto Roll Damage"]]<br /><br />
<br />
<br />
{{mbox | text = '''NOTE:''' If your character sheet's Settings have "Auto Damage Roll" set to "Don't Auto Roll Damage" under General Options, the damage will not be listed underneath the AC roll result in chat. The damage was rolled, but presently hidden from view. Anyone can see the damage delivered by manually unfolding the roll result open by hovering your mouse over the roll result in chat and clicking on the attack/spell's name.}}<br />
<div style="clear: both"></div><br />
<br />
===(12) Personality Traits, Ideals, Bonds, and Flaws===<br />
These text fields lock to prevent accidental edits. When a sheet is first created, these fields are unlocked and given a dashed yellow border to the top of the field to showcase that they're editable. To lock the field after entering text, click on the gear icon in the upper right corner of the field. This will remove the yellow border and the field will conform in height to display everything within it.<br />
<br />
There presently isn't a means to format the raw text (italicize, bold, font alignment, etc) within these fields and any line breaks are stripped out. If you ever need to edit the content again while the field is locked, mouse over the desired field and the gear icon will reappear in the top right. Clicking on that will unlock the field once again for edits.<br />
<br />
===(13) Class & Other Resources===<br />
[[File:5E_OGL_Sheet_Resources.png]]<br />
<br />
The Class & Other Resource Blocks can be used to keep track of either an item quantity you have in your equipment (like arrows in a quiver), or skills that don't fit into the other sections on the sheet (like a '''Sorcerer's Sorcery Points''', a '''Cleric's Channel Divinity''' at higher levels, or the number of rounds a '''Barbarian''' has been '''Raging''' so far in a combat encounter).<br />
<br />
There are 3 fields per Block:<br />
* Resource Max:<br />
** The Resource Max field is a text box which allows you to quantify exactly what you're tracking (ex. "Total: 10 Rounds").<br />
* Resource:<br />
** The Resource field is a numeral that you dial up or down or input directly.<br />
* Resource Name:<br />
** The Resource Name is a text box that allows you to label the resource when you click on the light grey "OTHER RESOURCE" label to overwrite it with your own.<br />
**"OTHER RESOURCE" is placeholder text<br />
<br />
<br />
A resource block will be filled automatically if you checkmark an Equipment item as "USE AS A RESOURCE" & the Item Quantity field will be paired with the Resource field in the Resource block & vice versa (you'll need to click outside of the field or hit Enter for changes to refresh across the sheet). If the two resource blocks given by default are not enough then you can add additional blocks by hovering over the section & clicking the "Add" (+ symbol) button.<br />
<br />
The Item Name will also be added to the Resource Name field, however the Resource Max field is apparently not linked to the Item currently.<br />
<br />
If you drag & drop an ammunition item type from the Compendium into your character sheet, the item is added to the Equipment block & is automatically listed & linked as an Other Resource.<br />
<div style="clear: both"></div><br />
To call the first set of class resources use:<br />
* Class Resource <code>@{class_resource}</code><br />
* Other Resource <code>@{other_resource}</code><br />
<br />
<br />
To call the Repeating resources use<br />
* Repeating Resource 1st left<code>@{repeating_resource_$0_resource_left}</code><br />
* Repeating Resource 1st right<code>@{repeating_resource_$0_resource_right}</code><br />
* Repeating Resource 2nd left<code>@{repeating_resource_$1_resource_left}</code><br />
* Repeating Resource 2nd right<code>@{repeating_resource_$1_resource_right}</code><br />
* etc.<br />
<br />
<br />
If you want to do a basic Full Readout of the Repeating Resource, the Format would be (Top Left to Bottom Right):<br />
* Class: <code>@{class_resource_name}: @{class_resource} / @{class_resource|max}</code><br />
* Other: <code>@{other_resource_name}: @{other_resource} / @{other_resource|max}</code><br />
* Left 0: <code>@{repeating_resource_$0_resource_left_name}: @{repeating_resource_$0_resource_left} / @{repeating_resource_$0_resource_left|max}</code><br />
* Right 0: <code>@{repeating_resource_$0_resource_right_name}: @{repeating_resource_$0_resource_right} / @{repeating_resource_$0_resource_right|max}</code><br />
* Left 1: <code>@{repeating_resource_$1_resource_left_name}: @{repeating_resource_$1_resource_left} / @{repeating_resource_$1_resource_left|max}</code><br />
* Right 1: <code>@{repeating_resource_$1_resource_right_name}: @{repeating_resource_$1_resource_right} / @{repeating_resource_$1_resource_right|max}</code><br />
* etc.<br />
<br />
===(14) Tool Proficiencies===<br />
[[File:5E_OGL_Sheet_Tool_Proficiencies.png|left]]The Tool Proficiencies block is for listing a character's Tool Proficiency skills. At the bottom of this block is an "Add" (<span style="font-family:Pictos;">&</span> symbol) button. Clicking this will add a new entry to this block where you can add all of the relative stats for a specific tool proficiency, say Woodcarver's Tools. You can set the level of proficiency to either Proficient, Expertise, or Jack of All Trades. The roll bonus for that tool will reflect the proficiency level selected. Next is an Attribute drop down menu where you can select which character attribute to roll with for a proficiency check. One of the options you can choose is "QUERY ATTRIBUTE" which when you click on the Tool Proficiency to roll it, you will be prompted to choose which attribute you would like to use. The attribute used for the check will be up to the GM when it is time to make the roll check. If there is any additional bonus modifiers that come along with the tool in question, you can input it in the "MODS:" field.<br />
<br />
Once you finished filling out the stats for this tool you can click the <span style="font-family:Pictos;">y</span>(gear) icon at the top right of the entry to hide the stat fields and leaving behind just the rollable button. You can roll by either clicking on this rollable button or dragging it to your [[Macro Bar]].<br />
<br />
You can also use this section to create custom skills or rolls for your campaign setting or home-brew ruleset. Check out the [[#Custom Skills and Stats|Advanced Use]] section for further details.<br />
<br />
====Global Skill Modifier====<br />
You can add a special entry to the Tool Proficiencies & Custom Skills block to handle to global Attacks and Damage modifications to rolls. An example is if the character is under the influence of the Guidance spell and can roll a 1d4 in addition to the result of their skill check. This feature is enabled from the [[#Settings Page|Settings Page]] under General Options. Once enabled, a checkbox will be added at the bottom of the Tool Proficiences & Custom Skills block with a text field to enter the additional die roll.<br />
<br />
For this example, you could enter "1d4[Guidance]" in the global checkbox's text field that you can enable when the character is under the effects of the Guidance spell. The word between the brackets becomes a label that can be seen when you mouse over the roll result in chat. While this Global Modifier is checked, every roll made from the Tool Proficiencies & Custom Skills block and the Skills block will add this modifier to the result.<br />
<div style="clear: both"></div><br />
<br />
===(15) Other Proficiencies & Languages===<br />
[[File:5E OGL Sheet Proficiencies.png|left]]<br />
This block can be set up to be Compendium Compatible (where you can add repeating sections for individual items) or as one resizable free-text field to enter whatever you wish in here. If you don't feel the Tool Proficiency block is needed (as in, you don't feel like your party will ever have to roll individual tool sets), you can store a character's Tool Proficiencies here instead. There presently isn't a means to format the raw text (italicize, bold, font alignment, etc). You can adjust this block's behavior by going to the Settings Page of the sheet and going to the General Options block to change whether this block uses the Simple or Compendium Compatible layout.<br />
<br />
When the Other Proficiences & Languages block is made Compendium Compatible, each repeating field lists a Type selection field and a Proficiency text field. Type has the following options available from its drop down selection menu: Language, Weapon, Armor, Other. <br />
<p style="clear:both;"></p><br />
<br />
===(16) Equipment===<br />
[[File:5E OGL Sheet Equipment.png|framed|right|The Equipment block of the PC Sheet]]<br />
The Equipment block at the bottom of the page has 2 different versions: a Simple version that features a single plain text field where you can track all of your equipment in any format you wish and a Compendium Compatible version that allows you to drag and drop items from the Compendium to automatically populate repeated sections for each indivdual piece of equipment.<br />
<br />
To swap between the two different Equipment block versions, first, go to the sheet's Settings Page (gear icon at the top right of the page) and then to the "General Options" section. Here, on the field labeled "Inventory", you can select between "Simple" or "Compendium Compatible" respectively. Like the name implies, if you want to be able to copy items directly from the Compendium using drag and drop, you must use the Compendium Compatible version. Dragging item entries from the Compendium to the character sheet will add it fully filled in the Equipment section as well as other automated actions described below.<br />
<br />
====Automated Compendium Functionality====<br />
If you populate the Equipment block by dragging and dropping <span style="font-family:Pictos;">i</span> [[Compendium]] items, there are several automatic features that occur when the entries you drag in our equipment items.<br />
Auto-Equip: Every item dragged to the sheet is automatically equipped in the Equipment Section<br />
*'''Weapons:''' A weapon dragged in from the Compendium will add an attack in the Attacks and Spellcasting section for that item.<br />
*'''Armor:''' Armor that is dragged in from the Compendium will add its bonus to the Armor Class (while equipped) section. If you drag multiple pieces of armor to the same sheet and at least two armor entries are equipped at once, a warning will pop up in red at the top of the Equipment Block that the Armor Class isn't being correctly calculated because of the bonus overlap. This warning will dissapear when you unequip down to a single set of armor.<br />
*'''Magical/Wondrous Items:''' Items that modify Attributes, Saves, AC, To Hit, Damage, Spell Attacks, and Spell DC will add that bonus to those elements on the sheet. In most cases, the attribute that is being modified will highlight in blue and followed with an asterisk to showcase that the attribute is being modified by an item. Mousing over the modified number will display the base value of that attribute before the item's modification is applied. This stat modification only applies if the item is equipped in the Equipment section and it will remove its bonus if it is unequipped.<br />
*'''Ammunition:''' Items dragged in from the Compendium that are used for ammunition such as arrows, bolts, darts, and slingstones, will automatically populate and link to an Other Resource field.<br />
<br />
====Manually Adding Items====<br />
You can also add items manually by hovering over the block and clicking the "Add" button (+ symbol). Each equipment entry, by default, show fields for quantity, name, and weight of an item. If you hover over a row and click the small "information" icon (grey-filled circle with a lowercase i centered in it) that appears at the bottom right of the entry you can also set some additional features. <br />
<br />
*'''Equipped Checkbox:''' The checkbox changes the appearance of the Item Name so it's easier to tell what your character currently has equipped from a glance. When left unchecked, the Item Name's font turns grey. When checked, the Item Name becomes a solid black.<br />
*Use As A Resource Checkbox: When checked, this will enable one of the Class Resource blocks and list the item name and its quantity within it. The quantity is tied between the two so changing it in one will be reflected in the other field after clicking outside the field.<br />
*'''PROP:''' This is a text field where you would take note of weapon properties such as ''finesse'', ''versatile'', or ''light''.<br />
*'''MODS:''' This is a text field where you would take note if an item (likely magical) would modify your stats in some fashion such as a character's Attributes, Saves, Skills, AC, To Hit, Damage, Spell Attacks, and Spell DC. If a stat is modified here, its attribute value will become highlighted in blue and adjusted by the supplied modifier listed here. An asterisk is appended to the right of the value to also signify that it has been modified by an item. While your mouse is hovering over the attribute, it will revert back to its unmodified total so you can refer back to its pre-moddified value.<br />
**The format for a stat modification is ''stat name:n'' where n is the stat bonus (ex. ''Strength:21'')<br />
*'''Description Field:''' This is a simple text field to include a description of the particular item and of any special qualities or effects it might have on the player.<br />
Some if not all of these fields will be filled in automatically when adding from the Compendium (where applicable).<br />
<br />
Both versions of the equipment field have the sections for each of the [https://app.roll20.net/compendium/dnd5e/Treasure#h-Treasure coins] you may find on your adventures: copper(CP), silver(SP), electrum(EP), gold(GP), and platinum(PP).<br />
<br />
====Encumbrance====<br />
If you are following Encumbrance rules, the <span style="font-family:Pictos;">i</span> [[Compendium|Compendium Compatible]] Equipment block will automatically calculate and track the weight of your character's backpack if you enter the weight values for any of the items in your Equipment list. When your character becomes encumbered, and depending on its severity, the words ENCUMBERED, HEAVILY ENCUMBERED, or IMMOBILE will display in red underneath the TOTAL WEIGHT value. You can also choose to follow Simple, Variant Encumbrance rules, or not follow Encumbrance rules at all by toggling it off on the [[D&D 5E by Roll20#Settings Page|Settings Page]] under "General Options".<br />
<br />
====Mods====<br />
The Mods field of each piece of equipment can modify the values of ability scores, AC, saving throws, Skill (Ability) checks and more. What follows is a list of the modifiers, and the proper syntax for adding them.<br />
<br />
All modifiers are separated by commas. There are other modifiers that can appear the mod field, used in creating the item from a compendium drag and drop operation, but the modifiers below have live effects on the character sheet, depending on if the item is marked as “equipped”.<br />
<br />
'''replace the <code>+n</code>, with the number you want.''' For example, if you want to boost Animal Handling skill by 3, you look at the table and find <code>Animal Handling +n</code>, so you will add to your item <code>Animal Handling +3</code>.<br />
<br />
{| class="wikitable" <br />
|-<br />
! Modifier<br /><br />
! Effect<br /><br />
|-<br />
| style="width: 20%;" | '''Combat Modifiers'''<br />
| '''These affect items that provide attacks (Appear in the attack section of the character sheet)'''<br />
|-<br />
| Melee Attacks +n<br />
| Adds +n hit "Magic Bonus" to that attack. It is not global, and only affects a weapon(melee or ranged), not an item, staff or other category. The bonus is figured into the attacks display on the 5e sheet.<br />It is NOT ''Melee Attack''.<br />
|-<br />
| Melee Damage +n<br />
| Adds +n damage "Magic Bonus" to that attack. It is not global, and only affects a weapon(melee or ranged), not an item, staff or other category. The bonus is listed separately in the attacks display on the 5e sheet.<br />
|-<br />
| Spell Attack +n<br />
| Adds a global +n to the character's Spell Attack bonus.<br />It is NOT ''Spell Attacks.''<br />
|-<br />
| '''Saving Throws'''<br />
| '''All modifiers stack with “Saving Throws +n'''<br />
|-<br />
| Strength Save +n,<br />Dexterity Save +n,<br />Constitution Save +n,<br />Intelligence Save +n,<br />Wisdom Save +n,<br />Charisma Save +n<br />
| Adds a +n to the indicated saving throw<br />''Do not use a colon.''<br />
|-<br />
| Saving Throws +n<br />
| Adds a Global Modifier to ALL saving throws.<br />
|-<br />
| Spell DC +n<br />
| Adds a global +n to a spell casting character’s Spell Save DC.<br />It is NOT Spell ''Save'' DC.<br />
|-<br />
| '''Ability Scores'''<br />
| <br />
|-<br />
| Strength +n,<br />Dexterity +n,<br />Constitution +n,<br />Intelligence +n,<br />Wisdom +n,<br />Charisma +n<br />
| Provides a bonus to the indicated ability score, which will appear in blue on the sheet while the bonus is active.<br />Do not use a colon. ''Strength: +10'' will do nothing<br />
|-<br />
| Strength n,<br />Dexterity n,<br />Constitution n,<br />Intelligence n,<br />Wisdom n,<br />Charisma n<br />
| Replaces the indicated ability score, which will appear in blue on the sheet while the bonus is active.<br />Do not use a colon. ''Strength: 10'' will do nothing<br />
|-<br />
| '''Skills'''<br />
| <br />
|-<br />
| Acrobatics +n,<br />Animal Handling +n,<br />Arcana +n,<br />Athletics +n,<br />Deception +n,<br />History +n,<br />Insight +n,<br />Intimidation +n,<br />Investigation +n,<br />Medicine +n,<br />Nature +n,<br />Perception +n,<br />Performance +n,<br />Persuasion +n,<br />Religion +n,<br />Sleight of Hand +n,<br />Stealth +n,<br />Survival +n<br />
| Adds the value to the indicated Skill roll. Note that in this case, the <code>+</code> and a colon are optional. <code>Acrobatics +5</code>, <code>Acrobatics 5</code>, <code>Acrobatics: +5</code>, <code>Acrobatics: 5</code> will all add <code>5</code> to the character’s Skill roll. For consistency and to guard against future functionality, it’s probably best to follow the format for ability scores, and use a plus sign with no comma: <code>Acrobatics +5</code>.<br />There is no Global Skill modifier<br />
|-<br />
| '''AC'''<br />
| <br />
|-<br />
| AC +n<br />
| By itself, <code>AC: 13</code> adds 13 to the character’s Armor Class. It does not replace it. <br /><br />If <code>Shield</code>, <code>Light Armor</code>, <code>Medium Armor</code>, or <code>Heavy Armor</code> is also in the mods field, it will change the calculation.<br />''<code>Light Armor, AC: 13</code>'' will give a formula of 13 + dex mod<br />''<code>Medium Armor, AC: 13</code>'' will give a formula of 13 + dex mod (max +2)<br />''<code>Heavy Armor, AC: 13</code>'' will give you flat AC 13<br />''Shield, AC: 13'' would add 13 to the your AC. The Shield keyword is superfluous in this case.<br />''<code>Shield, AC: 2</code>'' will just add 2 to the AC.<br />Finally, a bare modifier, such as for a Ring of Protection can just be written as <code>AC: +2</code> or <code>AC +1</code>.<br /><br />Shield or bare AC bonuses will stack with other armor mods on different items. You cannot equip multiple armors simultaneously, or have a custom armor equation on the settings tab and wear an armor. This will generate a flag.<br /><br />The + and a colon are semi-optional. <code>AC +5</code>, <code>AC: +5</code>, <code>AC: 5</code> will all work. However, <code>AC 5</code> will do nothing. For consistency and to guard against future functionality, it’s probably best to indicate a base AC as <code>AC: n</code> and a Shield as <code>AC +n</code>.<br />At this point, there is no way to differentiate between Ranged AC and Melee AC, though some magic items such as the ''Arrow Catching Shield'' make the distinction.<br />
|}<br />
<br />
<br />
<br />
<div style="clear: both"></div><br />
<br />
===(17) Features & Traits===<br />
[[File:5E OGL Sheet Features Traits.png|thumbnail|left|The Compendium Compatible itemized version of the Features & Traits section]]<br />
The '''Features and Traits '''-block is the place to store '''Class-''', '''Race-''' and '''Background Features''', '''Feats''', and other special notes about your character or of a certain piece of equipment or ability. When using the Charactermancer, the previously mentioned features appears in this section.<br />
<br />
This block can be set up to be <span style="font-family:Pictos;">i</span> [[Compendium|Compendium Compatible]] (where you can add repeating sections for individual items) or as one resizable free-text field to enter whatever you wish in here. You can adjust this block's behavior by going to the [[D&D 5E by Roll20#Settings Page|Settings Page]] of the sheet and going to the '''General Options'''-block to change whether this block uses the Simple or Compendium Compatible layout. <br />
<br />
When adding items to the Compendium Compatible version of this block, you have the <code>Name</code> field, a <code>Source</code>-field where you can choose between (Racial, Class, Feat, Background, or Other) , a <code>Source Type</code>-text field to describe the type, and then the multilined <code>Description</code>-textbox. Clicking on the <span style="font-family:Pictos;">y</span>(gear)-icon in the top right corner of the item will lock/unlock the item's editability. When locked down, a <span style="font-family:Pictos;">w</span>(chat bubble)-icon appears when you mouse over the feature/trait. Clicking on the <span style="font-family:Pictos;">w</span> will share this feature's description in the {{Text Chat}}.<br />
<br />
There presently isn't a means to format the raw text (italicize, bold, font alignment, etc) of the Simple version or in the Description section of either version of the Features & Traits block.<br />
<br />
You can drag-n-drop '''Feats''' from the compendium, even though they can't be selected in the Charactermancer on levelup.<br />
<br />
PC Features and Traits can be called using an ability roll:<br />
<code>%{selected|repeating_traits_$0_output}</code><br />
Simply increase the $0 value to access all Features and Traits listed on the character sheet, $1, $2, $3...<br />
<br />
<p style="clear:both;"></p><br />
<br />
==Bio Page==<br />
[[File:D&D5E-Roll20-BIO-tab.png|right|thumb|250px|The Bio Page of the PC Sheet]]The Bio page, opened by selecting "BIO" from the 4 buttons near the top right of the sheet, is comprised of free-form text fields that can be used to keep track of less "structured" information about your character. You can use this page to describe your character's appearance, keep track of who their allies are and what organizations they've worked for, and on this page is a section to supplement the inventory list, on the front page, with the "Treasure" section, where you can keep track of all the loot you find along your travels.<br />
===Bio Header===<br />
[[File:D&D5E-Roll20-Bio-header.png|550px]]<br /><br />
<br />
The header of the Bio page contains the basic run down of a character's physical appearance.<br />
*'''Character Name:''' This is carried over from every single PC Page and matches the character journal's name<br />
*'''Age:''' The character's current age<br />
*'''Size:''' The size classification for the race type (Medium for most cases)<br />
*'''Height:''' The character's height<br />
*'''Weight:''' The character's weight<br />
*'''Eyes:''' The character's eye color<br />
*'''Skin:''' The character's skin color<br />
*'''Hair:''' The character's hair color/style<br />
<br />
===Character Appearance===<br />
While the Bio Header describes the bare bone physical characteristics of a PC, this field is for fleshing out the visual peculiarities and/or cues of your character. Does you character have a piercing gaze? A stooped posture? Are they fancily dressed or are their clothes moth-eaten? In essence, this field is for everything and anything one would note about the character–from the equipment or garb they wear to how they comport themself.<br />
<br />
===Allies & Organization===<br />
This text field is for listing important or campaign relevant NPCs that the character may have a connection with. It's also for keeping track of faction allegiance. In the case of ''Dungeons & Dragons''' Forgotten Realms world, a PC could be a member of the Harpers or the Emerald Enclave, among other major factions who are all vying for power of the continent.<br />
<br />
===Character Backstory===<br />
This field is for listing your character's pre-campaign history, their relations, and the pertinent places they have been to in the past.<br />
<br />
===Additional Features & Traits===<br />
This text field is a continuation of the [[#.2817.29_Features_.26_Traits | Features & Traits]] section of the Core Page. The section on the Core Page is a good place for commonly utilized features of a character or briefly jotting down an abbreviated list. This field on the Bio page gives you more real estate to fully write down everything you need in whole.<br />
<br />
===Treasure===<br />
This text field is where you can list all the loot you've collected while searching bodies and delving through dungeons. Since much of these effects are transient and are likely to be used, given away, or sold to the highest bidder at the earliest opportunity, this may be preferable place to keep this list of items rather than adding them to the itemized Compendium Compatible Equipment section (if you have that version enabled).<br />
<br />
==Spell Page==<br />
[[File:D&D5E-Roll20-Spells-tab.png|right|thumb|400px|The Spell Page]]The Spell page, opened by selecting the "SPELLS" button from the four buttons near the top right of the sheet, is used to keep track of all of the powerful magics at your character's fingertips.<br />
<br />
===Spell Page Header===<br />
[[File:D&D5E-Roll20-Spells-header.png|550px]]On the Spells page Header you can set the ability modifier that will be used for casting spells. Selecting the Spellcasting Ability block will allow you to select an attribute from a dropdown, and this will be used in all relevant spell rolls. This attribute will be set automatically when you select a spell casting class. The next two blocks, the Save DC and Attack Bonus will be set automatically based on the class that is selected on the Core page.<br />
<br />
===Spellcasting Ability===<br />
The Spellcasting Ability modifier will automatically update, depending on the class you select on the Core page, to the correct ability modifier for your class. If, for some reason, you need to change this value you can click on the modifier listed in this section and it will give you a drop-down list of all available ability modifiers.<br />
<br />
===Spell Save DC & Attack===<br />
The Spell Save DC and Spell Attack Bonus sections cannot be changed manually, but are just a visual output of modifiers that will be happening behind the scenes. The Spell Attack Bonus is the number that will be added to all spell attack rolls, automatically.<br />
<br />
The Spell Save DC refers to the Save DC that enemies will have to beat when they are trying to dodge/resist your incoming spells. Say, Fred the Sorcerer casts Lightning bolt, and his Spell Save DC is 14. Any enemies hit by his attack will have to make a DEX save and try to beat 14. If they manage to beat the attack, then they are only grazed and take half of the damage. If they don't beat 14, then they take the full damage of the attack instead.<br />
<br />
===Spell Levels & Spells Per Day===<br />
The main section of the Spells page lists 10 sections, ranging from 0 to 9, representing the Cantrips (0) and spells level 1 - 9 where the level of the spell is listed in the triangle on the left of each section header. The number in the left square of the header represents the total number of Spell Slots, in other words, the maximum number of times a spell of this level can be cast in between long rests. This number will be set automatically depending on the level of your character, but can be modified by clicking the up or down arrow or just entering a number in the space provided. The number in the right-most box in the headers is the Slots Remaining value that can be used for you to keep track of the number of times you've cast a spell at this level.<br />
<br />
===Adding Spells===<br />
[[File:D&D5E-Roll20-Spells-Icons.png|framed|right]]<br />
When you drag spells from the <span style="font-family:Pictos;">i</span> [[Compendium]] to the sheet, a new spell entry will be added to the Spell Page under the appropriate level header. This will copy over all corresponding information linked to the spell, as well as creating an attack entry in the [[D%26D_5E_by_Roll20#.2811.29_Attacks_.26_Spellcasting|Attacks & Spellcasting]]-block on the "Core" page, if the spell can be used as an attack. The name of the spell will be listed to the left of the entry and to the right are icons for whether the spell is a Ritual (R), requires Concentration (C), and lists whether there is a Verbal (V), Somatic (S), or Material (M). There is also a circle at the far left of the entry that can be toggled to be filled in with red or left empty. This toggle represents spells that are Prepared for the day and are available for a player's convenience to help track this.<br />
<br />
You can manually add spells by selecting the <span style="font-family:Pictos;">&</span> under any of the Spell Level headings. This will present you with a blank template where you can enter all of the information about a spell. By default, the spell card only contains non-attack information about a spell. If the spell IS an attack you can change the "Output" selector from "Spellcard" to "Attack", this will show some additional input fields to fill out the attack information about the spell. Switching this input will also add an attack entry to the [[D%26D_5E_by_Roll20#.2811.29_Attacks_.26_Spellcasting|Attacks & Spellcasting]]-section on the [[#Core Page|Core page]] so this spell attack can also be cast from the main page. All of these sections are linked, so changing information in one place will also change the corresponding information in the other location. To save your edits, click on the gear icon at the upper right of the entry to collapse the spell entry.<br />
<br />
You can edit any spell at any time, by hovering your mouse over the entry to make a <span style="font-family:Pictos;">y</span> icon appear on the left. Clicking on the <span style="font-family:Pictos;">y</span> will roll out the spell once more to be edited.<br />
<br />
==Settings Page==<br />
[[File:D&D5E-by-Roll20-Settings-Page.png|thumb|right|400px|The Settings tab of the sheet, accessed from the '''<span style="font-family:Pictos;">y</span>''' icon ]]<br />
The Settings page, accessed by selecting the <span style="font-family:Pictos;">y</span>(gear) icon from the four buttons near the top right of the sheet, is where you can make changes to some parts of your character sheet that aren't represented on the other pages.<br />
<br />
===Class Options===<br />
In the class options section is where you have access to some important parts of your character, that usually are managed in the background. They are placed here so that, if needed they can be modified as well.<br />
<br />
'''Hit Dice:''' This section will be set automatically depending on the class chosen on the [[#Core Page|Core page]], but can be changed here by selecting the value and choosing a new one from the drop-down menu. This option is used whenever the "Hit Dice" section is used on the Core page.<br />
<br />
'''Carrying Capacity Modifier:''' This modifier allows you to increase the weight that a character can carry before they become encumbered.<br />
<br />
'''Global Magic Attack Modifier:''' This modifier will affect all spell attacks rolled from the sheet.<br />
<br />
'''Magic Caster Level:''' By default, a character's caster level is tethered to their class level. This option allows you to set the caster level manually, so you can have it differ from the character's class level. This will automatically change the Spell Slots Total for each spell level on the [[#Spell Page|Spells page]].<br />
<br />
'''Spell Save DC Mod:''' The Spell Save DC is normally a field you can't edit from the Spell page and is set by the character's class and level. This modifier allows you to alter that value.<br />
<br />
'''Spell Icons:''' This option will allow you to choose to turn off all the Spell Icons (R, C, V, S, & M), show them all, or only display only the ritual and concentration icons.<br />
<br />
'''Halfling Luck:''' Use this checkbox if your character is a Halfling that happens to take advantage of the Halfling Luck race feat. Using this feat will automatically re-roll any 1s rolled for attacks and skills or ability checks/saves.<br />
<br />
'''Arcane Fighter/Rogue:''' These checkboxes can be used to keep track of when your Fighter or Rogue-classed character actually has access to spells.<br />
<br />
===Multiclass Options===<br />
If you are taking advantage of the D&D 5E multiclassing you can keep track of it in this section. Any levels to your character's additional classes must be changed here, and will then be reflected in the header portion of the sheet. Once you've added additional classes in this section, any time you roll Hit Dice from the Core page it will ask you which classes hit dice you wish to use.<br />
<br />
Note: Be sure to not re-include your main class in this section, or your final level calculation will be incorrect.<br />
<br />
===Custom Class Options===<br />
If you are playing a class that is not part of the D&D 5E Compendium, you can input the important class information in this section, and checking the "Use Custom Class" checkbox will replace the main class selection with your custom built class.<br />
<br />
===Spell Slot Modifiers===<br />
This section allows you to manually modify how many spell slots your character has available for each spell level from 1 to 9.<br />
<br />
===Attribute Options===<br />
'''Attribute Modifiers:''' With this section you can manually adjust the individual Attribute Scores for Strength, Dexterity, Constitution, Intelligence, Wisdom, and Charisma.<br />
<br />
'''Initiative Modifier:''' Usually, your initiative modifier is just based off of your DEX modifier, but if you happen to find a magical item that enhances these rolls this is where you will put that bonus. This modifier will be used whenever the [[#.287.29_Armor_Class.2C_Initiative.2C_.26_Speed|Initiative]]-section is rolled on the Core page.<br />
<br />
'''Initiative Style:''' This setting allows you to select whether Initiative will be rolled with Advantage, Disadvantage, or rolled normally with a single d20 (default).<br />
<br />
'''Add DEX Tiebreaker to Initiative:''' If you would like to enable a tie breaker component to Initiative, this checkbox will enable adding your dexterity Attribute Score as a decimal value to your Initiative roll. So if you have a character with a dexterity attribute score of 14, your initiative modifier will change from a 2 to a 2.14.'<br />
<br />
'''Global Armor Class Modifier:''' This setting will modify your armor class and will be taken into account regardless of the equipment the character uses.<br />
<br />
'''Armor Class Tracking:''' There are three options available: The Automatic version that's default to the sheet where it adds 10 + your DEX modifer and then takes any armor equipped into account. A Custom version which expands out a formula upon selection where you can input your own formula for armor tracking, or you can turn Off Armor Tracking entirely. When turned off, you will need to manually adjust the Armor Class field on the Core page.<br />
<br />
===Save Options===<br />
'''Save Modifiers:''' With this section you can manually adjust the individual Save modifiers for Strength, Dexterity, Constitution, Intelligence, Wisdom, and Charisma.<br />
<br />
'''Death Save Modifier:''' A normal death save is usually just a D20 against a dc of 10, but if you're lucky enough to have a bonus to death saves, this is where you will put your bonuses. This modifier will be represented any time a "Death Save" is rolled from the Core page.<br />
<br />
'''Global Saving Throw Modifier:''' If you have an affect that would modify all saving throws, this option makes it easier to adjust your Save modifiers than having to go in and change each one individually. This modifier will be used every time any save is rolled from the sheet.<br />
<br />
===Skill Options===<br />
If your class offers the ability to achieve "Expertise" in a skill, or if you are using a Bard with the "Jack of All Trades" feat, this is where you will make these adjustments. There is also a section to add flat modifiers to any of your skills if your character has an archetype ability like Remarkable Athlete or a feat that adds a flat bonus to a skill. You can add expertise to any skill by clicking the value next to it and choosing "Expertise" from the drop-down menu. If your Bard has the Jack of All Trades feat, you can check the checkbox at the bottom of this section and it will automatically give half of your character's proficiency points to any skill check that doesn't have full proficiency.<br />
<br />
'''Passive Perception Modifier:''' This option will add a bonus to a character's Passive Perception which is not something you can change directly from the Core page of the sheet.<br />
<br />
===General Options===<br />
The General Options section has some important options that deal more with how the sheet works, rather than actual character creation. Most importantly, the NPC checkbox at the top, which will change the sheet to be the NPC version which is shaped to more easily track an NPC's information.<br />
<br />
'''Roll Queries - Always/Toggle/Query/Never Roll Advantage:''' This option will change how advantage is rolled for all attacks. It defaults to always roll advantage, which means that every time an attack is rolled it will roll twice and present the outcome of both rolls. This is useful for both advantage and disadvantage, otherwise you can just choose either the left or the right to be the default roll. Toggle adds a set of buttons at the top of the sheet to manually switch your advantage options between rolls. If Query is chosen, every time a roll is made it will ask you whether or not it's advantage. If Never is chosen, then it will always roll just a single dice per attack roll.<br />
<br />
'''Whisper Rolls to GM:''' Like above, you have the option to Never/Toggle/Query/Always whisper rolls to the GM. When this option is enabled, the attack roll will only be whispered to the GM and not made public.<br />
<br />
'''Auto Damage Roll:''' By default, damage rolls will not be rolled automatically, but only when you click the attack in the chat window. This is useful because you can choose to only roll damage when an attack hits. Using this option you can make the character always roll damage with every attack.<br />
<br />
'''Core Die Roll:''' You can change the core die (by default it is 1d20) to something else entirely here.<br />
<br />
'''Proficiency Bonus:''' By default, the character's Proficiency Bonus is calculated by class level. This setting allows you choose to calculate this bonus via By Level (the default), via a Proficiency Die as described in the Dungeon Master's Guide, or a Custom calculation which rolls out a field to enter a roll formula for the bonus.<br />
<br />
'''Global Save/Skill/Attack/Damage Modifier Field:''' This series of checkboxes will add new entries to the Saving Throws, Tools Proficiencies & Custom Skills, and Attacks & Spellcasting blocks respectively to add global modifiers (like if a character is under the effects of a Bless or Guidance spell). Each entry will have a Global label in grey at the bottom of its entry and a field to enter the modifier bonus. If you include a word in brackets with the bonus formula (ex. "1d4[Bless]"), the word enclosed in the brackets will appear when you mouse over a roll to see it's formula.<br />
<br />
'''Add Character Name to Templates:''' This option allows you to turn this on or off. When it is on, the character's name is listed in the roll template when rolls are made from the sheet. If the character sheet in question is for an NPC, you will likely want to have this off so the rolls don't accidentally show your hand of what sort of monster your party is facing. This setting is off by default.<br />
<br />
'''Auto Level Calculations:''' This option allows you to turn this on or off. When it is on, adjusting the character's class level will automatically update the character's proficiency bonus, Hit Dice, and spell Slot totals (if the class is a spellcaster).<br />
<br />
'''Encumbrance:''' This option dictates how encumbrance is handled on the Equipment block of the Core page. This requires your Inventory to be set to "Compendium Compatible" to automatically calculate and track the weight of your character's backpack if you enter the weight values for any of the items in your Equipment list. When your character becomes encumbered, and depending on its severity, the words ENCUMBERED, HEAVILY ENCUMBERED, or IMMOBILE will display in red underneath the TOTAL WEIGHT value. This setting has three options: Simple Encumbrance Rules, Variant Encumbrance Rules, or not follow Encumbrance rules at all by toggling it off from this.<br />
<br />
'''Inventory:''' With this option allows you to either have your Equipment block be "Compendium Compatible" or "Simple". The Simple version of the Equipment block will give you single text field to log your inventory. The Compendium Compatible version tracks weight, quantity, and attack options in an itemized list for every equipment item you add to the block.<br />
<br />
'''Features & Traits:''' This option can set the Features & Traits block to be either a single text field or a repeated section that will be Compendium Compatible to list traits and features in an itemized list.<br />
<br />
'''Proficiencies & Languages:''' This option can set the Proficiences & Languages block to be either a single text field or a repeated section that will be Compendium Compatible to list traits and features in an itemized list.<br />
<br />
'''Ammo Tracking (API Required):''' When using the 5th Edition OGL Companion API Script in your game (Pro Subscriber feature), you can set attacks to weapons using ammunition to automatically subtract from their tally in their Resource block. So if your character is equipped with a bow, rolling its attack will automatically remove an arrow from its Resource block.<br />
<br />
===Transition Options(outdated)===<br />
{{mbox | text = This feature doesn't seem to exist on the sheet any longer, so the info in this section is outdated}}<br />
<br />
If your campaign previously used the [https://wiki.roll20.net/DnD5e_Character_Sheet#Intro Community Contributed] or [https://wiki.roll20.net/index.php?title=DnD5e_Shaped_Character_Sheet&oldid=11112#General_Information Shaped Legacy] 5th Edition Character Sheets and you are swapping over to this one, we have an automated conversion tool that will clear or merge elements left over from those two sheets. This procedure can only be done ''once'' and can not be undone. It is recommended that you make a copy of your campaign first before attempting a sheet transition.<br />
<br />
There is also a checkbox that hides this feature entirely from the sheet. If you hide this by mistake, you can gain access to it again by creating a new character journal.<br />
<br />
=The NPC Sheet=<br />
''See Also:'' '''[[D&D5E by Roll20 NPC Attributes]]'''<br />
<br />
One of the most useful parts of the D&D 5E by Roll20 Character Sheet is that it contains both a PC sheet ''AND'' an NPC sheet. An NPC doesn't normally require the depth a PC sheet needs, so the NPC sheet is a much more slimmed down character sheet that doesn't require multiple pages like its PC counterpart. You can access this version of the sheet by going to the Settings Page, by clicking the gear icon near the top right of the sheet, and then checking the NPC checkbox. This will switch the sheet to the NPC version. You can switch back at any time by unchecking the NPC option under General Options on the new page.<br />
<br />
==NPC Options==<br />
[[File:5E_OGL_Sheet_NPC_Options.png|right|thumb|250px|The NPC Options Section]]This is the area where all of the NPC's stats will be entered, it covers everything from the NPC's name, to how strong or quick or smart it is, to what languages it speaks. Most of the fields in this section are just text fields used to keep track of information about the NPC. All of the information entered in these fields will be visible in the stat block once the NPC options are hidden. <br />
<br />
<br />
Any text that appears in light grey is placeholder text. It's there to offer you an example of what the content would be for any given field. <br />
<br />
By default, no skill or ability checks will show up in the NPC's stat block. Once you've added a value to the corresponding skill or ability save, they will appear. If for some reason the NPC will have to make a check with a skill or ability it does not have any bonus in, you can enter a 0 as the modifier for that check and it will add it to the list in the stat block below.<br />
<br />
The XP of an NPC auto-calculates based on its given challenge rating.<br />
<br />
If the NPC is a spellcaster, you can check the checkbox beside '''SPELLCASTING NPC''' and this will add a spell list section that utilizes the spell list and its functionality from the PC version of the sheet.<br />
<br />
At default, you can add Traits and Actions in their respective places after the Challenge Rating and XP area of the Stat Block. For Reactions and Legendary Actions, you need to enable them from the NPC Options section. For Reactions, check off the '''HAS REACTIONS''' checkbox. This will add a new sections to the Stat Block for you to add Reactions to. If an NPC is a monster with Legendary Actions then you must enter the number of actions that monster has access to each turn in the '''LEGENDARY ACTIONS:''' field. Once you add a number here, an additional section will appear in the stat block below, where you can add the specific legendary actions that the monster is able to do.<br />
<br />
The NPC sheet supports Compendium drag & drop. If you want to add a new monster to your game just drag the monster from the <span style="font-family:Pictos;">i</span> [[Compendium]]-tab of the [[Sidebar]] and drop it to anywhere on the Tabletop. This will automatically create a new journal entry named the same as the Compendium entry and will copy all of the information on that compendium page directly into the new sheet. If you have purchased any of the Compendium expansions that expands on the available NPCs like the Monster Manual or Volo's Guide to Monster, a token of that NPC will be added to the Tabletop that will have its stats automatically set and linked to the new journal entry.<br />
<br />
{{mbox | text = '''Note:''' If you already have a journal entry in your {{journal}}-tab with the exact same name as the <span style="font-family:Pictos;">i</span> [[Compendium]] entry, the drag and drop will not work as this automation will stop to prevent overwriting existing content the user has already created. If a drag and drop of an NPC Compendium page does not create a journal entry, run a search for that NPC's name in your Journal to see if an entry already exists. If you do not want to delete the older entry, renaming it will allow the drag and drop to work as expected.}}<br />
<br />
===General Options===<br />
Within the NPC Options section, directly below the Legendary Actions field, is the General Options that are featured on the PC Sheet: NPC checkbox, WHISPER ROLLS TO GM, and the AUTO DAMAGE ROLL options. <br />
<br />
*NPC checkbox<br />
*WHISPER ROLLS TO GM<br />
*AUTO DAMAGE ROLL<br />
*NPC NAME IN ROLLS<br />
*ADD DEX TO TIEBREAKER TO INITIATIVE<br />
<br />
Unchecking the NPC checkbox from here will revert the sheet back to the PC Sheet.<br />
<br />
===Hiding NPC Options===<br />
Once all of the desired information has been entered, you can click the <span style="font-family:Pictos;">y</span>(gear) icon at the top right to hide this section. This leaves behind just the NPC's stat block where you can make all of your rolls from. You can re-open this section to edit the information at any time by clicking on the <span style="font-family:Pictos;">y</span> icon again. It's in the same location regardless if you're looking at NPC Options or the NPC stat block.<br />
<br />
==The NPC Stat Block==<br />
[[File:5E OGL Sheet NPC v2.png|right|thumb|250px|An NPC stat block for a griffon]]Following NPC Options is the NPC Stat Block that is built off of what you input in the NPC Options section. This area may look very similar to a stat block you may find in a monster bestiary or published adventure.<br />
<br />
<br />
Any section of the stat block that has a corresponding roll will have click-able text. For example, if the NPC has to make a CON check, you can click the CON attribute to roll a CON check with all of the required modifiers automatically included. If you added a value to one of the skill modifier fields then that skill will show up in the NPC's "Saving Throws" list where you can click it to make a saving throw roll using that skill's modifier.<br />
<br />
The first section of the Stat Block mirrors all the information you added in the NPC Options section. This content is meant exclusively for rolling and can not be edited directly. You will need to change them from the NPC Options section.<br />
<br />
===Traits===<br />
Traits are pieces of information about an NPC that isn't covered by the NPC options section. These are entered directly onto the NPC's stat block. If you click the "<span style="font-family:Pictos;">&</span>" button that appears right below the "Senses/Languages/Challenge Rating" section it will add a blank entry where you can add a single trait for that NPC. Each Trait Entry features a bold title field which is then followed by a larger text box for the description of the trait. You can add any number of Traits for any NPC.<br />
<br />
===Actions===<br />
NPC actions can be used for any number of things. Each entry initially offers an Action Name field as well as a large text field for the Action description. The checkbox for ATTACK, once checked, adds more structured data fields needed for an attack roll (Type, Range/Reach, To Hit bonus, Target, Damage Roll, and Damage Type). To add a new entry you will select the <span style="font-family:Pictos;">&</span> button that appears below the Actions section. Once all of this is complete you can click the <span style="font-family:Pictos;">y</span>(gear) icon at the top of this entry to hide the input fields, leaving just the action text. You can show this information, or roll the attack, in the chat box by clicking the text for the action. If you need to make further modifications to any action you can hover over the row you wish to edit, then click on the <span style="font-family:Pictos;">y</span>(gear) icon again. This will show all of the action information input fields again. You can add any number of Actions for any NPC.<br />
<br />
===Bonus Actions===<br />
NPC bonus actions are typically not listed on the sheet, and are usually referenced in the Traits section. However, if a player wishes to use this section, it is available if the 'Bonus Action' checkbox is selected. The fields work the same as the Actions section.<br />
<br />
===Reactions===<br />
Once enabled from the NPC Options section, a new heading labeled "Reactions" and its relevant section is added to the stat block that allows you to add Reactions. These entries operate just like Traits.<br />
<br />
===Spells===<br />
Once enabled from the NPC Options section, a new heading labeled "Spells" and its relevant section is added to the stat block that allows you to add Spells. These entries will operate identically to how Spells are added and handled on the PC Sheet with the one noted exception that there is only a single column of spell entries. You can drag spells from the Compendium to add spell entries just like you would with the PC's Spell sheet. Any and all spells added to the character sheet are shared between the NPC and the PC versions.<br />
<br />
===Legendary Actions===<br />
If a number value is added to the LEGENDARY ACTIONS field in the NPC Options section, the Legendary Actions heading and section is added at the very bottom of the stat block and lists some verbiage on how many actions are available to be used on a given turn. This number is dictated by what you entered in the NPC Options. These entries operate the same way as Traits.<br />
<br />
==Rolling for Initiative for NPCs==<br />
There are two ways to roll for Initiative on the NPC sheet. You can click on the NPC's Name to roll for Initiative or you can roll from the die icon labeled INIT that is listed to the right of the Armor Class and Hit Points section of the NPC sheet, towards the top. If you have the Turn Tracker tool open, having the NPC token selected while rolling Initiative will automatically add the NPC and its initiative roll to the tracker. Creatures on the GM layer that are added to the tracker in this fashion will have their entries hidden from the players.<br />
<br />
<br />
You can also create a global Macro that will pop up as a Token Action button in the upper left hand corner of the tabletop every time a token is selected. This will allow you to roll without looking at the NPC sheet at all. The macro formula should look just like this:<br />
<br />
<code>%{selected|npc_init}</code><br />
<br />
=Advanced Use=<br />
<br />
===Custom Skills and Stats===<br />
You can set up any number of custom skills or rolls from the [[#Tool Proficiencies|Tool Proficiencies]] section just underneath the skill section on the Core tab. [[#Class & Other Resources|The Resources]] section is also useful for tracking custom stats to your campaign, game setting, or home-brew rules. There are also various options available from the Settings page to modify attributes, skills, saves, spells, and more.<br />
<br />
===Target Roll Buttons===<br />
A useful way for GMs and Players to reference their abilities is by dynamically setting up a handful of macros that can be used on a token linked to a character, rather than having to roll directly from the sheet. To do this, you'll set up a global macro from the {{Collections}}-tab. You can also write these directly in the {{Text Chat}}.<br />
<br />
In the examples, the <code>selected</code> part can be replaced with <code>target</code>, a character's name, or it's character ID.<br />
<br />
Here are some examples:<br />
<br />
'''PC'''<br />
* Attributes: <code>%{selected|strength}</code>, <code>%{selected|strength_save}</code> | Will roll the Strength Check and Strength Save for the selected [[token]](if the [[Link Token|token is linked to a sheet]])<br />
* <code>%{selected|acrobatics}</code><br />
* <code>%{selected|initiative}</code><br />
* <code>%{selected|death_save}</code><br />
* <code>%{selected|hit_dice}</code><br />
<br />
'''NPC'''<br />
* <code>%{selected|npc_init}</code><br />
* <code>%{selected|npc_str}</code><br />
* <code>%{selected|npc_stealth}</code><br />
* <code>%{selected|npc_hpformula}</code><br />
====Dynamic References to Repeating Sections====<br />
The example we'll be using today is setting up the 1st NPC action:<br />
<code>%{selected|repeating_npcaction_$0_npc_action}</code><br />
Now whenever you use this macro it will roll the first NPC action of whichever NPC token you have selected. You can set up a roll for each action by incrementing the 0 by 1 for each action you wish to add (I.E. <code>$1</code>, <code>$2</code>, <code>$3</code>). Here is a list of important repeating section rolls and their formulas:<br />
<br />
* Player Attack/Spell Attack <code>%{selected|repeating_attack_$0_attack}</code><br />
* Player Attack/Spell Damage <code>%{selected|repeating_attack_$0_attack_dmg}</code><br />
* Player Attack/Spell Critical Damage <code>%{selected|repeating_attack_$0_attack_crit}</code><br />
* Player Global DMG mod <code>%{selected|repeating_damagemod_$0_global_save}</code><br />
** Attr names: <code>global_damage_name</code>, <code>global_damage_damage</code>, <code>global_damage_critical_damage</code>, <code>global_damage_type</code><br />
* Proficiencies <code>%{selected|repeating_proficiencies_$0_output}</code><br />
* Tool/Custom Skill <code>%{selected|repeating_tool_$0_tool}</code><br />
* Traits/Feats: <code>%{selected|repeating_traits_$0_output}</code><br />
<br />
* Spellbook Cantrip <code>%{selected|repeating_spell-cantrip_$0_spell}</code><br />
* Spellbook Level 1 <code>%{selected|repeating_spell-1_$0_spell}</code><br />
* Spellbook Level 2 <code>%{selected|repeating_spell-2_$0_spell}</code><br />
* Spellbook Level 3 <code>%{selected|repeating_spell-3_$0_spell}</code><br />
* Spellbook Level 4 <code>%{selected|repeating_spell-4_$0_spell}</code><br />
* Spellbook Level 5 <code>%{selected|repeating_spell-5_$0_spell}</code><br />
* Spellbook Level 6 <code>%{selected|repeating_spell-6_$0_spell}</code><br />
* Spellbook Level 7 <code>%{selected|repeating_spell-7_$0_spell}</code><br />
* Spellbook Level 8 <code>%{selected|repeating_spell-8_$0_spell}</code><br />
* Spellbook Level 9 <code>%{selected|repeating_spell-9_$0_spell}</code><br />
<br />
'''NPC'''<br />
* NPC Traits/Abilities<code>%{selected|repeating_npctraits_$0_npc_roll_output}</code><br />
* NPC Actions/Attacks<code>%{selected|repeating_npcaction_$0_npc_action}</code><br />
* NPC Attack Damage<code>%{selected|repeating_npcaction_$0_npc_dmg}</code><br />
* NPC Attack Critical Damage<code>%{selected|repeating_npcaction_$0_npc_crit}</code><br />
* NPC Bonus Actions<code>%{selected|repeating_npcbonusaction_$0_npc_action}</code><br />
* NPC Legendary Actions<code>%{selected|repeating_npcaction-l_$0_npc_action}</code><br />
* NPC Mythic Actions<code>%{selected|repeating_npcaction-m_$0_npc_action}</code><br />
* NPC Spells<code>%{selected|repeating_spell-npc_$0_spell}</code><br />
<br />
===Directly Referencing Attributes===<br />
You can discover the name of most of the attributes in the sheet by hovering over them. After a couple of seconds a title will pop up and tell you how to referencing them. You can call attributes in an Ability Rolls by using <code>@{attributename}</code>. If you want to directly reference it in a roll that isn't saved on the sheet, you need to specify the character's name, or use either the <code>selected</code> or <code>target</code> key works.<br />
<br />
'''Examples:'''<br />
* <code>/em attempts to grapple and gets [[1d20+@{strength_mod}]]</code> custom [[Journal#Attributes_.26_Abilities_Tab|Ability call]], saved on the A&A-tab<br />
* <code>/r 1d20+@{Alice|strength_mod}+@{Alice|pb}</code> macro that calls a specific character<br />
* <code>/em have @{selected|hp} out of @{selected|hp|max} left.</code> macro that uses stats from a token(token must be selected before rolling)<br />
* <code>The Enemy's AC is @{target|npc_ac}</code> macro prompt the user to select a target token on the map, and uses it's stats.<br />
<br><br />
<br />
See [[Macros#Attribute_Macros]] for further general details/examples on the syntax.<br />
====PC====<br />
Here are a list of some of the more important stats:<br /><br />
<br />
'''Attributes/Saves:'''<br />
<br />
* Str: <code>strength, strength_mod, strength_save_bonus</code><br /><br />
* Dex: <code>dexterity, dexterity_mod, dexterity_save_bonus</code><br /><br />
* Con: <code>constitution, constitution_mod, constitution_save_bonus</code><br /><br />
* Int: <code>intelligence, intelligence_mod, intelligence_save_bonus</code><br /><br />
* Wis: <code>wisdom, wisdom_mod, wisdom_save_bonus</code><br /><br />
* Cha: <code>charisma, charisma_mod, charisma_save_bonus</code><br />
<br><br />
'''Skills:'''<br />
<br />
<code>athletics_bonus<br /><br />
acrobatics_bonus<br /><br />
animal_handling_bonus<br /><br />
arcana_bonus<br /><br />
deception_bonus<br /><br />
history_bonus<br /><br />
insight_bonus<br /><br />
intimidation_bonus<br /><br />
investigation_bonus<br /><br />
medicine_bonus<br /><br />
nature_bonus<br /><br />
perception_bonus, passive_wisdom<br /><br />
performance_bonus<br /><br />
persuasion_bonus<br /><br />
religion_bonus<br /><br />
sleight_of_hand_bonus<br /><br />
stealth_bonus<br /><br />
survival_bonus<br /><br />
</code><br />
<br />
'''AC, Proficiency, HD etc'''<br />
<br />
<code>pb</code>(Proficiency Bonus)<br><br />
<code>inspiration</code><br><br />
<code>ac<br /><br />
initiative_bonus<br /><br />
speed<br /><br />
hp, hp|max, hp_temp<br /><br />
hit_dice, hit_dice|max, hitdietype<br /><br />
weighttotal<br /><br />
</code><br />
<br />
'''Spells'''<br />
<br />
<code>spell_save_dc, spell_attack_bonus<br /><br />
lvl1_slots_total, lvl1_slots_expended<br /><br />
lvl2_slots_total, lvl2_slots_expended<br /><br />
lvl3_slots_total, lvl3_slots_expended<br /><br />
lvl4_slots_total, lvl4_slots_expended<br /><br />
lvl5_slots_total, lvl5_slots_expended<br /><br />
lvl6_slots_total, lvl6_slots_expended<br /><br />
lvl7_slots_total, lvl7_slots_expended<br /><br />
lvl8_slots_total, lvl8_slots_expended<br /><br />
lvl9_slots_total, lvl9_slots_expended<br /><br />
</code><br />
<br />
Spells, repeating sections:<br><br />
<code>repeating_spell-cantrip<br><br />
repeating_spell-1<br><br />
repeating_spell-2<br><br />
repeating_spell-3<br><br />
repeating_spell-4<br><br />
repeating_spell-5<br><br />
repeating_spell-6<br><br />
repeating_spell-7<br><br />
repeating_spell-8<br><br />
repeating_spell-9</code><br> <br />
<br />
Cantrip stats(most should also work for lvl.1-lvl.9):<br><br><br />
Full statname is spell level + (rowID or row number) + attribute name, e.g. <code>repeating_spell-1_$0_spellname</code> is the spell name of your first Lvl 1 spell, <code>repeating_spell-4_$1_spelldescription</code> is the description of your second lvl.4 spell.<br />
<br />
<code>spellname<br><br />
spellrange, spellcastingtime, spelltarget, spellduration<br><br />
spellschool<br><br />
spellritual<br><br />
spellconcentration<br><br />
spellcomp_v, spellcomp_s, spellcomp_m<br><br />
spellcomp_materials<br><br />
spell_ability<br><br />
spelloutput<br><br />
spellattack<br><br />
spelldamage, spelldamagetype, spelldamage2, spelldamagetype2<br><br />
spellhealing<br><br />
spelldmgmod, spell_damage_progression<br><br />
spellsave, spellsavesuccess<br><br />
spelldescription<br><br />
spellclass, spellsource</code><br />
<br />
'''Items'''<br><br />
<code>cp sp ep gp pp</code><br><br />
(copper pieces, silver, gold, electrum, platinum)<br />
<br />
<code>repeating_inventory_$#_itemcount<br><br />
repeating_inventory_$#_itemname<br><br />
repeating_inventory_$#_itemweight<br><br />
repeating_inventory_$#_equipped<br><br />
repeating_inventory_$#_useasresource<br><br />
repeating_inventory_$#_hasattack<br><br />
repeating_inventory_$#_itemproperties<br><br />
repeating_inventory_$#_itemmodifiers<br><br />
repeating_inventory_$#_itemcontent</code><br><br />
<br />
* <code>equipped</code>, <code>useasresource</code>, <code>hasattack</code> are checkboxes, with value 1 if checked.<br />
* <code>itemmodifiers</code> is for of item changes any stats, like <code>AC +2</code> adding +2 to AC when equpped.<br />
* <code>itemcontent</code> is the item description<br />
<br><br />
'''The class_resource and the other_resource'''<br><br />
<br />
<code>class_resource</code> and <code>other_resource</code> are static resources. That is to say, you need to keep in mind that they are NOT a part of the repeating section, even though it definitely looks that way on the character sheet.<br><br />
<br />
You use these to access them<br />
<br />
<code>class_resource</code><br><br />
<code>class_resource_max</code><br><br />
<code>class_resource_name</code><br><br />
<code>other_resource</code><br><br />
<code>other_resource_max</code><br><br />
<code>other_resource_name</code><br><br />
<br />
'''The repeating resources'''<br><br />
<br />
Any resources that appear beneath the "class resource" and the "other resource" are a part of the "repeating resources" section. This section is known for being confusing for beginners, so it deserves a bit of clarification.<br />
<br />
First, keep in mind that this is one section (not two sections, as people often think), and that "repeating_resource" is its section prefix.<br />
<br />
Second, keep in mind that you need to skip past the row with the "class resource" when you're figuring out the address of the row that you want to refer to. So basically, if you want to refer to the row that is directly below the row that contains the "class_resource", then you would add "_$0" (to form "repeating_resource_$0". And then the next row is "_$1", and so on.<br />
<br />
Third, keep in mind that if you add "_resource_left" (to form "repeating_resource_$0_resource_left"), then you are specifying that you are talking about the CURRENT VALUE of the leftmost resource in that row. And if you add "_resource_left_max", then you are specifying that you are talking about the MAX VALUE of the leftmost resource in that row.<br />
<br />
Here is a complete list of all the fields that you can access in the "repeating_resource" section. Just replace the "#" character with which row you want to access.<br />
<br />
<code>repeating_resource_$#_resource_left</code><br><br />
<code>repeating_resource_$#_resource_left_max</code><br><br />
<code>repeating_resource_$#_resource_left_name</code><br><br />
<code>repeating_resource_$#_resource_right</code><br><br />
<code>repeating_resource_$#_resource_right_max</code><br><br />
<code>repeating_resource_$#_resource_right_name</code><br><br><br />
<br />
<br />
'''Features/Class Traits'''<br />
<br />
<code>repeating_traits_$0_output<br><br />
repeating_traits_$#_name<br><br />
repeating_traits_$#_source<br><br />
repeating_traits_$#_source_type<br><br />
repeating_traits_$#_description<br><br />
</code><br />
<br />
'''Other/Settings:'''<br />
<br />
<br><br />
<code><nowiki>wtype</nowiki></code> (whisper type, can have one of these values:)<br />
* <code><nowiki></nowiki></code> (empty for never whisper)<br />
* <code><nowiki>@{whispertoggle}</nowiki></code> (show the buttons on sheet that can toggle between options)<br />
* <code><nowiki>?{Whisper?|Public Roll,|Whisper Roll,/w gm }</nowiki></code><br />
* <code><nowiki>/w gm</nowiki></code> (always whisper)<br />
<br />
<br />
'''Global modifiers'''<br />
<br />
* <code>repeating_savemod_$0_global_save_roll</code><br />
* <code>repeating_skillmod_$0_global_skill_roll</code><br />
* <code>repeating_tohitmod_$0_global_attack_roll</code><br />
* <code>repeating_damagemod_$0_global_damage_damage</code><br />
<br />
====NPC====<br />
Some stats are the same as for PCs<br />
<br />
<code>npc_name<br><br />
npc_ac<br><br />
hp, hp|max<br><br />
npc_speed<br><br />
npc_challenge<br><br />
npc_xp</code><br />
<br />
Attributes: <code>strength_base, strength_mod</code> (same as PCs)<br />
Saves:<br />
<br />
<code>npc_str_save_base</code>,<code>npc_dex_save_base</code>, <code>npc_con_save_base</code>,<code>npc_int_save_base</code>,<code>npc_wis_save_base</code><code>npc_cha_save_base</code><br />
Skill bonus:<code>npc_acrobatics_base</code>, <code>npc_animal_handling_base</code> etc.<br />
<br />
Damage/Conditions stuff:<br />
<br />
<code>npc_vulnerabilities<br><br />
npc_resistances<br><br />
npc_immunities<br><br />
npc_condition_immunities</code><br />
<br />
Spells:<br />
<br />
<code>npcspellcastingflag</code> (set to "1" if caster, empty otherwise) <br />
<code>spellcasting_ability</code><br />
<code>globalmagicmod </code> (global magic attack modifier)<br />
<code>caster_level</code><br />
<code>spell_dc_mod</code> (spell save DC mod)<br />
<br />
Spells are identical to PC section<br />
<br />
Other:<br />
whisper is same as PCs<br />
<br />
<code>npc_name_flag</code> (show/hide npc name in rolls, value is either <code><nowiki>{{name=@{npc_name}}}</nowiki></code> or <code>0</code>)<br />
<br />
<br />
<sup>Note: anything with the Suffix of <code>|max</code> requires some form of Prefix, such as <code>selected|</code> making the call for such a thing look something along the lines of <code>@{selected|hp|max}</code>. The <code>|max</code> Suffix specifically calls the box on the right of the selected Attribute's Line, for example, you could fill in the Weight Total's 2nd Box with <code>@{strength}*15</code> & whenever you call <code>@{selected|weighttotal|max}</code> it will tell you your 5e standard Maximum Carry Capacity for your current Strength Score.<br />
<br />
===Custom AC Items===<br />
You can add pieces to your inventory and manually give them AC or magic bonuses that will figure into their calculations automatically. Inside the item options is a section for "MODS:". Add <code>Ac +1</code> to add an armor class bonus.<br />
<br />
===Roll Templates===<br />
''Main Article:'' '''[[D&D 5e by Roll20 Roll Templates]]'''<br />
<br />
The '''D&D5E by Roll20''' Character Sheet also includes a series of [[Roll Templates]] that you can use to dress up your own custom macros. Roll Templates provide additional layout and styling options for the display of roll results.<br />
<br />
{{ex}}<br />
[[File:5e-rolltemplate-ex1-2021.png|200px|right|none]]<br />
Rolls stealth for selected npc token, using it's stealth proficiency.<br />
<code><nowiki>/w gm &{template:npcatk} {{attack=1}} {{name=Shadow}} {{rname=Shadow Stealth}} {{rnamec=Hide}} {{r1=[[@{selected|d20}+@{selected|npc_stealth} + 6]]}} {{always=1}} {{r2=[[@{selected|d20}+@{selected|npc_stealth} + 6]]}} {{description=While in dim light or darkness, the shadow can take the Hide action as a bonus action. Its stealth bonus is **also** improved to +6 }}</nowiki></code><br />
<br />
===Magic Missile Spell===<br />
{| role="presentation" class="wikitable mw-collapsible mw-collapsed" style="float:right; margin-left: 10px;margin-right: 60px;"<br />
| Image of the Spell's settings<br />
|-<br />
| [[File:Magic-Missile-5E-2020.png|right|frame|The Magic Missile Spell]]<br />
|}<br />
<br />
RAW, Magic Missile is rolled once, and the single roll is then used for each hit. So by default the spell rolls <code>1d4+1</code>. (See [[Talk:D&D 5E by Roll20#Old Magic Missile Discussion]] for more info.)<br />
<br />
You can modify the spell to instead roll 3d4+3 at first level, and then in the ''HIGHER LVL CAST DAMAGE'' section, set it to <code>1d4+1</code>.<br />
<br />
To automatically use higher-level spell slots with Magic Missile, you have to write a 0 into the ''HIGHER LVL CAST DAMAGE'' section of the spell and select any die. It will show the box for selecting higher-level spell slots when launching Magic Missile, but since it multiplies the higher-level damage cast by 0, the added roll doesn't show up in the chat, making it roll a single die for every missile while using any level spell slot.<br />
<br />
=API=<br />
{{pro only|section}}<br />
[[API:Introduction|API Scripts]] allow for greater customization and functionality to how Roll20 operates beyond what it can do at default. This section will list some info on using various APIs that interact with the character sheet.<br />
<br />
Example of APIs from the One-Click Install menu, that designed to be used with the '''D&D 5E by Roll20''' sheet:<br />
* '''5E BattleMaster'''<br />
* '''5E Resting in Style'''<br />
* '''CashMaster'''<br />
* '''Concentration'''<br />
* '''[[Script:It's a Trap|It's a Trap! -- D&D 5E Generic]] (should detect automatically what sheet is used)<br />
** {{repo|Roll20/roll20-api-scripts/tree/master/ItsATrap_theme_5E_Generic#readme readme}}<br />
* '''ShortRest'''<br />
* '''SpellMaster'''<br />
* '''WildShape'''<br />
<br />
A good number of the more general APIs have built in settings for configuring them for usage with the 5E sheet, such as '''GroupInitiative''', '''GroupCheck''', '''Experience Tracker''', '''[[PowerCards]]''' <br />
<br />
* '''[[GroupCheck]]:''' <code>!group-check-config --import 5E-OGL</code> will configure the API for use with this sheet<br />
* '''[[GroupInit|GroupInitiative]]:''' before use, API need to be configured for the sheet, either through the menu preset, or using the command: <code>!group-init --add-group --Bare </code><br />
* '''CombatMaster:''' is by default configured with conditions for D&D 5E<br />
* '''[[ChatSetAttr]]:''' API that can create, edit, & delete stats on sheets. Example: [[Script:ChatSetAttr#Add_new_thing_to_Repeating_Section|Adding a new magic item to a sheet]], with one chat command <br />
* '''[[Script:Ammo]]''' can be used for updating ammo & spellslots when used<br />
<br />
==Utilizing the ''5th Edition OGL by Roll20 Companion'' API Script==<br />
'''{{repo|Roll20/roll20-api-scripts/tree/master/5th%20Edition%20OGL%20by%20Roll20%20Companion 5th Edition OGL Companion}}'''is an official companion script for the "D&D 5E by Roll20" character sheet. The Companion currently supports Ammo Tracking, Automatic NPC Tokens, Automatic Death Save Tracking, and Automatic Spell Slot Tracking. <br />
<br />
{{mbox | text = Installing & creating [[API]] Scripts is a {{Pro}} feature. In order to be able to access these advanced scripts, the [[GM]] of the campaign must be a [[Pro]] subscriber and enable it for their campaign.}}<br />
<br />
<br />
'''''How to Add the API Script to your Game'''''<br />
<br />
If you have a PRO account, you can install the API script by going to your game's Campaign Page and clicking on the '''Settings''' button, and then choosing '''API Scripts'''. This brings you to the API Scripts page for your current game. The Companion Script is part of the One-Click Community API Installation options. Under the Script Library tab, there is a drop down menu that lists all the available community created scripts. Scroll down till you find the '''System Toolbox''' category and select the "5th Edition OGL by Roll20 Companion" script. The version number, the script's author, and a brief description of what the script does will appear right below the drop down menu once it is selected. Below that, click on the blue "Add Script" button to add the script to your game.<br />
<br />
<br />
'''''List of API commands for the 5th Edition OGL Companion API Script'''''<br />
* <code>!5ehelp</code> - Gives a list of the script's API commands in the chat tab.<br />
* <code>!5estatus</code> - Lists the current status of the script's features in the chat tab.<br />
* <code>!ammotracking on/off/quiet</code> - Automatically expends linked resource when attack is made<br />
* <code>!autonpctoken on/off</code> - Automatically generates a NPC token on the GM's screen based on the default token when an NPC's health calculation is rolled<br />
* <code>!deathsavetracking on/off/quiet</code> - Automatically ticks off successes and failures when death saves are rolled, clearing on death, stabilization, or hp recovery<br />
* <code>!longrest <character name></code> - This will add Hit Dice recover and if spelltracking is on, this command will reset all of the character's spell slots to unspent.<br />
* <code>!npchp <character name></code> - Rolls NPC hit point totals using their formula and updates the token bar. If no character name is provided it will roll the selected tokens.<br />
* <code>!spelltracking on/off/quiet</code> - Automatically expends spell charges as cast, factoring in higher level casting, and spells marked as Rituals will not spend a spell slot.<br />
<br />
<br />
Options:<br />
* ''on'' - Toggles the functionality on (default)<br />
* ''off'' - Disables the functionality<br />
* ''quiet'' - Maintains functionality while preventing results from being output to the chat.<br />
<br />
<br />
===Automatic Ammunition Tracking===<br />
''Main Article:'' '''[[D&D 5E by Roll20: How to setup Ammunition and Resource tracker]]'''<br />
<br />
Automatic Ammunition Track is a feature that requires the above Companion API Script. Once installed, follow these instructions to enable automatic ammunition tracking in your game:<br />
<br />
This example sets up a Longbow with a quiver of Arrows to track.<br />
# On the Settings (Gear Icon) tab of a character sheet, under GENERAL OPTIONS, make sure that the INVENTORY option is set to "Compendium Compatible" and not "Simple".<br />
# While still under GENERAL OPTIONS, set the AMMO TRACKING feature to ON.<br />
# Create manually or drag a missile weapon (ex. Longbow) from the Compendium to your sheet.<br />
# Create manually or drag a missile type (Arrows) from the compendium to your sheet<br />
# Expand the missile type (Arrows) by clicking on the "I" information icon that appears when hovering the mouse over the item.<br />
# Select the USE AS RESOURCE checkbox. (ammunition items dragged from the Compendium will have this option automatically checked off)<br />
# On the CORE tab, expand the missile weapon (Long Bow) in the ATTACKS & SPELLCASTING section by clicking on the gear icon that appears when hovering over the attack.<br />
# In the AMMUNITION section put the exact name of the ammunition resource (Arrows). If you want to spend more than one piece of ammunition per shot you want to add the number of pieces after the name of the ammunition resource and a comma. (ex. ''Arrows,2'' )<br />
<br />
<br />
Now, any time the missile weapon (Longbow) is rolled, a piece of ammunition will automatically be spent and the chat will make note. Additionally after the first time the missile weapon is used the AMMUNITION section will update with the ID of the resource repeating section, this is normal and expected.<br />
<br />
<br />
===Automatic Spell Slot Tracking===<br />
<br />
Automatic Spell Slot Tracking is a feature that requires the above Companion API Script. Once installed, follow these instructions to enable automatic spell slot tracking in your game:<br />
* In the chat input area of the Sidebar, type ''!5estatus'' and press Enter, to check if spelltracking is set to 'on'.<br />
* If not, type ''!spelltracking on'' and press Enter to activate this feature.<br />
* Alternatively, you may type ''!spelltracking quiet'' and press Enter to activate this feature, while preventing spelltracking messages from being displayed in the chat.<br />
<br />
<br />
<br />
Once the Spell Slot Tracking has been activated, each time a spell is cast:<br />
# The number of cast spells of the appropriate level is updated in the Spell tab of the character sheet (see [[5th Edition OGL by Roll20|Spell Levels & Spells Per Day]]).<br />
# A message is output in the chat, displaying the spell level, the number of available spell slots and the number of used spell slots for this level.<br />
# Spell slots decrement as spells are cast. <br />
# Spells that are marked as a Ritual do not affect the tally of spell slots when cast.<br />
<br />
<br />
At any time, you can manually adjust this count directly in the Spell Page of the character sheet.<br />
<br />
=Updates=<br />
* {{hc|articles/360037772613-Change-Log Roll20 Changelog}} - Full Changelog of Roll20, updates for 5E sheet are included<br />
* {{fpl|10096810/ D&D 5th Edition by Roll20 (Q2Y2021)}} often has mentions of latest updates<br />
* Major Sheet Updates:<br />
** Feats can now be selected in Charactermancer {{fpl|8891809 June 2020}}<br />
** Game [[creator]] can select which [[compendiums]] are or aren't accessible in a game. [https://app.roll20.net/forum/post/8738570/release-note-for-may-26-2020 May 26 2020]<br />
<br />
=Known Issues=<br />
The sheet has a number of known bugs and issues, some which are mentioned in the sheet's latest forum thread.<br />
<br />
'''Charactermancer/Character Creation'''<br />
* '''Charactermancer & Compendium drag-n-drop doesn't work when sheet is in a separate window.''' This is [[Character_Sheets#Character_Sheet_in_a_separate_window|an inherit limitation to how character sheets work]] at the moment. <br />
* '''Multiclassing & spell selection''' - There are troubles when multiclassing spellcasters and getting to select spells from the right lists.<br />
* '''Duplicate races/classes from Essential Kit appear in selection''' You need to uncheck EK from your compendium for it to no longer appear in selections.<br />
<br />
<br />
'''General:'''<br />
* '''Warlock spell slots''' - The Warlock's spell slots don't work too well with the sheet, and most people use some manual adjustments for how they work. The number of spell slots also appears wrong in the Charactermancer.<br />
* '''NPC stat <code>desc</code> changed into <code>description</code>''' This was a recent update that broke some macros for people, resulting in error messages along: "can't find ''desc'' attribute" {{fpl|8297517/ release notes march 2020}}<br />
<br />
=Sheet Guides=<br />
* [[5E Macros]]<br />
* {{blog|638339117446578176/tome-of-tips-dungeons-dragons-5th-edition-ogl Tome Of Tips: The D&D 5E character sheet}}<br />
* {{yt.be|9BGGr97qJdY|Learning Roll20: EP01 Character Sheets (D&D 5E)}} 50min, by Roll20 (2020)<br />
<br />
=Related Pages=<br />
* D&D 5E by Roll20 sheet<br />
** [[D&D5E by Roll20 NPC Attributes]]<br />
** [[D&D 5e by Roll20 Roll Templates]]<br />
** [[D&D 5E by Roll20: How to setup Ammunition and Resource tracker]]<br />
* [[5E]] - general D&D 5E info for Roll20. Lists also the alterantive character sheets for 5E<br />
* [[D&D]] - Roll20 stuff on the various editions.<br />
* {{Compendium}}<br />
** [[Compendium Sharing]]<br />
* [[Character Vault]]<br />
<br />
=See Also=<br />
* {{repo|Roll20/roll20-character-sheets/tree/master/DD5thEditionLegacy Sheet sourcecode}} - (Public version of sheet code is 1½+ years behind from what is actually used)<br />
* {{hc|articles/360037772613-Change-Log Roll20 Changelog}} - Full Changelog of Roll20, updates for 5E sheet are included<br />
<br /><br />
<br /><br />
[[Category:Character Sheet Documentation]]<br />
[[Category:Official Sheet]]<br />
[[Category:DnD5E]]<br />
[[Category:Featured articles]]</div>5004103https://wiki.roll20.net/Script:ScriptCardsScript:ScriptCards2021-10-01T12:27:24Z<p>5004103: /* Repeating Section Access (--R) */</p>
<hr />
<div>{{revdate}}<br />
== Introduction ==<br />
'''ScriptCards''' provides a script interpreter that can be used to create powerful macros that display the results of player/NPC actions, or display other information in a pleasing visual format in your game's chat window. The scripting language contains variables (both dice-roll (enhanced numerics) and strings) as well, conditionals, branching, subroutines with parameters, and a set of built-in functions to simplify working with Roll20 information.<br />
{{script overview<br />
|name=ScriptCards<br />
|author={{user profile|2365448|Kurt J.}}<br />
|code=<br />
|version=1.4.0e<br />
|lastmodified=2021-09-24}}<br />
ScriptCards is not game-system specific, and can be used with any system/sheet. Near the end of this Wiki there is a section set aside for libraries that can implement system-specific tasks, with the hope that enthusiasts playing particular systems will create and share utility functions that can be utilized by the wider community.<br />
<br />
The default display style for ScriptCards output is similar to the format used to document player and NPC abilities in Dungeons and Dragons 4th Edition, but does not have any system ties to D&D4E.<br />
<br />
Current OneClick Version : 1.4.0e<br />
<br />
Current Development Version : 1.4.4<br />
<br />
'''''<big>Critically Important: ScriptCards does not use/parse inline rolls. ScriptCards includes its own built-in dice roll parser to allow for the use of variables inside dice rolls. As of version 1.2.3, ScriptCards will now take inline rolls and substitute the total result value in statement strings, meaning that you can utilize inline rolls but ScriptCards will only see the result of the roll, and not parse the roll components itself.</big>'''''<br />
<br />
* {{fpl|9752053/ ScriptCards thread}}<br />
** {{fpl|10000297/ Scritpcard API Working and Sharing}}<br />
* https://github.com/kjaegers/ScriptCards/tree/main/ScriptCards_API - GitHub repository for source before the one-click version is updated.<br />
* {{yt.be|hyR7Jnq4mQM ScriptCards Intro}} 45min, Jan 2021<br />
* {{yt.be|u50xvNzS9Zk ScriptCards Magic Missile Deep Dive}} 39min, Feb 2021<br />
<br />
<br />
__TOC__<br />
=== Is ScriptCards Related to [[PowerCards]]? ===<br />
<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
Check the '''[[#What to Know if you are Coming from PowerCards|What to Know if you are Coming from PowerCards]]'''-section for a comparison table between the two scripts.<br />
<br />
== What is a ScriptCard Script ==<br />
<br />
A ScriptCard Script is text written into the chat window (either typed directly, pasted, or run via a macro) that will produce a card of information in the [[text Chat|chat window]]. A ScriptCard Script is composed of an [[API]] command: <code><nowiki>!scriptcard {{ }}</nowiki></code> enclosing any number of lines that determine the output that will be added to the card. At it simplest, the following macro:<br />
<br />
<pre>!scriptcard {{ }}</pre><br />
<br />
Will produce just a title card that displays “ScriptCards” as the name:<br />
<br />
[[File:Scriptcard blank.png]]<br />
<br />
Of course, this is just the simplest type of macro and isn’t very useful. In order to produce useful output, we need to include lines between the <code><nowiki>{{</nowiki></code> and <code><nowiki>}}</nowiki></code> that direct the API script as to what it should do.<br />
<br />
== Structure of a ScriptCard Line ==<br />
<br />
All ScriptCard lines begin with two dashes, followed by an ''statement identifier character'' that lets ScriptCards what type of line it is. There are several of these, and they are detailed in the next section. After the line type identifier, a Tag name 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.<br />
<br />
Following the Tag is a vertical bar, and then the content of the line itself. Again, each type of line might interpret this content differently.<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Identifier !! Statement Type !! Tag !! Content !! Notes<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--/</nowiki> || Comment || unused || unused || The <code>--/</code> 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--#</nowiki> || 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").<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--+</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--=</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--&</nowiki> || Assign String 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. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--@</nowiki> || 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 (i.e., [[TokenMod|!token-mod]], or [[ChatSetAttr|!setattr]], etc.)<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--:</nowiki> || 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<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--^</nowiki> || Branch To || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--></nowiki> || Call Procedure || 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<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--<</nowiki> || 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.<br />
|- <br />
| style="white-space:nowrap" | <nowiki>--?</nowiki> || Conditional Branch || Condition to be evaluated || True Branch Label<nowiki>|</nowiki>False Branch Label || The condition will be evaluated and execution will jump to one of the two indicated branches (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 included a semicolon separated list of parameters. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--s</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--l</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--v</nowiki> || 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+'''''<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--e</nowiki> || Echo to Chat || Name to send chat command as || Chat message to send || Variable substitution takes place on the tag and content.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--R</nowiki> || Retrieve Repeating Section Row information || "find", "first", or "next" || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--~</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--c</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--i</nowiki> || Information Request || User Prompt;Button Caption || InfoType;VariableName;ParameterText || See full documentation below.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--d</nowiki> || 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. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--%</nowiki> || 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. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--*</nowiki> || 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.<br />
|}<br />
<br />
== ScriptCard Statement Type Details ==<br />
The sections below detail the individual statement types supported by ScriptCards<br />
<br />
=== Comment (--/) ===<br />
<br />
A --/ statement is ignored by the ScriptCards parser. You can use this type of statement to add comments and informational text to your script. <br />
<br />
Example:<br />
<pre><br />
!script {{<br />
--/|Script Name : Fireball<br />
--/|Purpose : Allow the player to cast a fireball and blow stuff up!<br />
.<br />
.<br />
.<br />
}}<br />
</pre><br />
<br />
=== Set Parameter (--#) ===<br />
<br />
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.<br />
<br />
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.<br />
<br />
'''''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.'''''<br />
<br />
Examples:<br />
<pre><br />
--#title|Magic Missile<br />
--#leftsub|Level 1 Spell<br />
--#rightsub|Force Damage<br />
</pre><br />
<br />
The three examples above set the “title”, “leftsub”, and “rightsub” values for the card to the content value for the line. <br />
<br />
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.<br />
Settings Lines do not produce output lines on the card.<br />
<br />
The following settings are available (note that parameter names are ''not'' case sensitive):<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Name !! Effect/Use !! Default Value !! Type<br />
|-<br />
| 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<br />
|-<br />
| allowplaintextinrolls || If set to a non-zero value, plain character text in rolls will be copied to the roll text || 0 || Per-Line<br />
|-<br />
| bodyFontFace || Name of the font used in the card rows || Helvetica || Global<br />
|-<br />
| bodyFontSize || Size of the text in the card rows || 14px || Global<br />
|-<br />
| bodybackgroundimage || Specify an image (content for a CSS background-image tag) for the body area || none || Global<br />
|-<br />
| buttonBackground || Background color for buttons created with [button][/button] || #1C6EA4 || Per-Line<br />
|-<br />
| buttonBorderColor || Border (outline) color for buttons created with [button][/button] || #999999 || Per-Line<br />
|-<br />
| buttonFontFace || Font Family specifier for captions on buttons created with [button][/button] || Tahoma || Per-Line<br />
|-<br />
| buttonFontSize|| Text size for captions on buttons created with [button][/button] || x-small || Per-Line<br />
|-<br />
| buttonTextColor|| Text color of labels on buttons created with [button][/button] || #FFFFFF || Per-Line<br />
|-<br />
| 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<br />
|-<br />
| deferralcharacter || Changes the meta script deferral sequence to the specified value || ^ || Per-Line<br />
|-<br />
| diceFontColor|| Color of the dice created with the [d4] [d6], etc. formatting markers || #1C6EA4 || Per-Line<br />
|-<br />
| dicefontsize || Size of the dice created with the [d4] [d6], etc. formatting markers || 3.0em || Per-Line<br />
|-<br />
| 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<br />
|-<br />
| disablerollprocessing || If set to a non-zero value, --= lines will not process dice rolls strings || 0 || Per-Line<br />
|-<br />
| emoteBackground || Background color of the emote area || #f5f5ba || Global<br />
|-<br />
| emoteFont || Name of the font used in emote area (above the title of the output card) || Georgia || Global<br />
|-<br />
| emoteFontColor || Color of the font in the emote area || None (Empty) || Global<br />
|-<br />
| emoteFontSize || Size of the font used in the emote area || 14px || Global<br />
|-<br />
| emoteFontWeight || Font weight for the font in the emote area || bold|| Global<br />
|-<br />
| emoteState || If set to anything other than "visible", the emote portion of the card will not be displayed || visible || Global<br />
|-<br />
| emoteText || Text to display in the emote portion of the card || None (Empty) || Global<br />
|-<br />
| emotefont || Name of the font used in the emote text area || font-family: Georgia, serif; font-weight: bold; || Global<br />
|-<br />
| evenRowBackground || Hex code for the background color for even rows || #eeeeee || Per-Line<br />
|-<br />
| evenRowFontColor || Hex code for the text color for even rows || #000000 || Per-Line<br />
|-<br />
| evenrowbackgroundimage || Specify an image (content for a CSS background-image tag) for the even card rows || none || Per-Line<br />
|-<br />
| executionlimit || Maximum number of script lines the interpreter will try to execute. This prevents "infinite loop" sandbox crashes || 40000 || Global<br />
|-<br />
| hideCard || If set to any non-default value, the entire card output will be suppressed || 0 || Global<br />
|-<br />
| 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<br />
|-<br />
| 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<br />
|-<br />
| lineheight || Vertical size of each line on the output card || normal || Per-Line<br />
|-<br />
| nominmaxhighlight || If set to anything other than "0", rolls will not display crit/fumble/mixed highlight colors. || 0 || Per-Line<br />
|-<br />
| norollhighlight || If set to anything other than "0", rolls will not be formatted (plain numbers) but will still get a tooltip with details ('''''v1.3.6b+''''') || 0 || Per-Line<br />
|-<br />
| oddRowBackground || Hex code for the background color for even rows || #d0e4f5 || Per-Line <br />
|-<br />
| oddRowFontColor || Hex code for the text color for odd rows || #000000 || Per-Line<br />
|-<br />
| oddrowbackgroundimage || Specify an image (content for a CSS background-image tag) for the odd crd rows || none || Per-Line<br />
|-<br />
| reentrant || Used to name a script for rentrant button use || 0 || Global<br />
|-<br />
| 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)0 || Global<br />
|-<br />
| rollhilightlineheight || Determines the height of the hilight box placed around roll results ('''''1.4.2+''''') || 1.0em || Per-Line<br />
|-<br />
| roundUp || If set to a non-default value, integer division will round up instead of down || 0 || Per-Line<br />
|-<br />
| showfromfornonwhispers || If set to a non-zero value, will include the sender on cards that aren't whispered || 0 || Global<br />
|-<br />
| 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<br />
|-<br />
| subtitleFontColor || Color of the text in the subtitle areas || #FFFFFF || Global<br />
|-<br />
| subtitleFontFace || Name of the font used on the subtitle sections || Tahoma || Global<br />
|-<br />
| subtitleFontSize || Size of the subtitle font || 13px || Global<br />
|-<br />
| subtitleSeperator || The character(s) that will be placed between leftsub and rightsub || <nowiki>&#x2666</nowiki>; || Global<br />
|-<br />
| tableBorderRadius || CSS specifier for how rounded the borders of the output card are. Use "0px;" for square borders || 6px; || Global<br />
|-<br />
| tableShadow || CSS specifier for the drop shadow under the output card || 5px 3px 3px 0px #aaa; || Global<br />
|-<br />
| tablebgcolor || Background color of the whole card. '''''Normally not visible''''' || #EEEEEE || Global<br />
|-<br />
| tableborder || Color of the border that surrounds the whole card || 2px solid #000000; || Global<br />
|-<br />
| 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<br />
|-<br />
| timezone || IANA Specifier for the local time zone, used in system/date functions || merica/New_York || Per-Line<br />
|-<br />
| title || Text displayed in the title area of the card || ScriptCards || Global<br />
|-<br />
| titleCardBackground || A hex color code representing the background color of the title area. || #1c6ea4 || Global<br />
|-<br />
| titleFontColor || Color of the text on the card title || #FFFFFF || Global<br />
|-<br />
| titleFontFace || Name of the font used on the title area || Contrail One || Global<br />
|-<br />
| titleFontLineHeight || Line spacing on the title area || 1.2em || Global<br />
|-<br />
| titleFontSize || Size of the title font || 1.2em || Global<br />
|-<br />
| titlecardbackgroundimage || Specify an image (content for a CSS background-image tag) for the title card area || none || Global<br />
|-<br />
| titlecardbottomborder || Border CSS specifier for the bottom of the title card area || 2px solid #444444; || Global<br />
|-<br />
| titlecardgradient || If set to non-zero value, will place a vertical gradient on the title card area || 0 || Global<br />
|-<br />
| usehollowdice || If set to a non-zero value, the hollow/outline versions of the dice fonts will be used || 0 || Per-Line<br />
|-<br />
| whisper|| Comma separated list of who to whisper the output to. Use "gm" for [[GM|GMs]] and "self" for the sender || none || Global|}<br />
|}<br />
<br />
''Setting Lines do not produce output lines on the card''<br />
<br />
=== Direct Output (--+) ===<br />
<br />
A direct output line display 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.<br />
<br />
Examples of Direct Output lines:<br />
<pre><br />
--+Hello|World<br />
--+Attack|The monster rolls [$Attack] to hit!<br />
--+Damage|@{target|token_name} is hit for [$Damage] [#3333AA][b]frost[/b][/#] damage.<br />
</pre><br />
<br />
Direct Output lines support inline formatting, roll variable replacement, character attribute references, and procedure variables.<br />
<br />
=== GM Output (--*) ===<br />
<br />
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. <br />
<br />
Example:<br />
<pre><br />
--+PlayerLine|This line is shown on the public card<br />
--*GMLine|This line will only be shown to GMs, on a separate card.<br />
</pre><br />
<br />
=== Roll Variable Assignment (--=) ===<br />
<br />
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.<br />
<br />
'''''All components of a roll equation should be separated with spaces.'''''<br />
<br />
Examples:<br />
<pre><br />
--=MissileDamage|1d4 + 1<br />
--=Attack|1d20 + @{selected|strength_mod} [STR] + @{selected|pb} [PROF]<br />
</pre><br />
<br />
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. Text enclosed in square brackets ([]) is considered "flavor text" and will be added to the result text but does not impact the roll result.<br />
<br />
The following dice formats are supported:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Format Pattern !! Example !! Description<br />
|-<br />
| XdY || 3d8 || Simple format. Roll a Y-sided die X times<br />
|-<br />
| XdYkhZ || 2d20kh1 || Roll Y-sided die X times and keep the highest Z number of dice<br />
|-<br />
| XdYklZ || 4d6kl3 || Roll Y-sided die X times and keep the lowest Z number of dice <br />
|-<br />
| XdY>Z || 5d6>3 || Roll Y-sided die X times and count a 1 for each roll greater than Z <br />
|-<br />
| XdY<Z || 5d6<3 || Roll Y-sided die X times and count a 1 for each roll less than Z <br />
|}<br />
<br />
'''''Note: The dice formulae below are supported in the development version of ScriptCards and will be merged with the table above when activated on OneClick'''''<br />
::{| class="wikitable"<br />
|-<br />
! Format Pattern !! Example !! Description<br />
|-<br />
| 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<br />
|-<br />
| 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<br />
|-<br />
| 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)<br />
|-<br />
| 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<br />
|}<br />
<br />
The following operators are supported in a roll equation:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Operator !! Operation<br />
|-<br />
| + || Addition <br />
|-<br />
| - || Subtraction <br />
|-<br />
| * || Multiplication <br />
|-<br />
| / || Division <br />
|-<br />
| \ || Integer Division (Rounds down) <br />
|-<br />
| % || Modulo (Remainder of Divison)<br />
|}<br />
<br />
Roll Variables can be accessed at any time after they have been created by using the [$VariableName] format, with the following optional modifiers:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Modifier !! Meaning<br />
|-<br />
| No modifier || In a Direct Output Line (<nowiki>--+</nowiki>) 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<br />
|-<br />
| .Total || The end result of the roll equation as an unformatted number <br />
|-<br />
| .Base || The cumulative result of any dice rolled in the Roll Text (Numeric modifiers are not included) <br />
|-<br />
| .Ones || The number of dice in the roll that came up as 1s <br />
|-<br />
| .Aces || The number of dice in the roll that came up as the maximum number on the die <br />
|-<br />
| .Odds || The number of dice in the roll that came up with an odd number <br />
|-<br />
| .Evens || The number of dice in the roll that came up with an even number <br />
|-<br />
| .RollText || The raw text of the roll that was use to generate the results <br />
|-<br />
| .Text || A text representation of the results of the roll, including the numbers rolled for each die <br />
|-<br />
| .tableEntryText || The text portion of the result of a table roll<br />
|-<br />
| .tableEntryImgURL || The image source portion of the result of a table roll<br />
|-<br />
| .tableEntryValue || Numeric value of tableEntryText (via parseInt). If a non-numeric value, will be 0<br />
|-<br />
| .Raw || The total numeric result without any formatting, even if placed somewhere formatting would normally be done. <br />
|}<br />
<br />
Examples:<br />
<pre><br />
--+Total Damage|[$MissileDamage.Total] (roll was 1d4+1)<br />
--+Base Damage|[$MissileDamage.Base] (without the +1)<br />
--=Attack|1d20 + @{selected|strength_mod} [STR] + @{selected|pb} [PROF] + [$BlessBonus] [Bless]<br />
</pre><br />
<br />
In this case, 1d4 will be rolled and stored in “BlessBonus”, which can then be used in the Attack line.<br />
<br />
'''''Mathematical Functions in Roll Expressions '''''<br />
<br />
The ScriptCards roll parser works from left to right, always maintaining a current value and applying whatever comes next to the total. The following in-line functions to the roll parser. These are:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Expression !! Meaning<br />
|-<br />
| {ABS} || Absolute Value<br />
|-<br />
| {CEIL} || Ceiling value (round up to the next whole number)<br />
|-<br />
| {FLOOR} || Floor value (round down to the next whole number)<br />
|-<br />
| {ROUND} || Round value (round up if the decimal portion is greater than 0.5, otherwise round down)<br />
|-<br />
| {NEGATE} || Multiply the value by negative one.<br />
|-<br />
| {SQRT} || Take the square root of the running value. ('''''1.4.1+''''')<br />
|-<br />
| {SQUARE} || Square the running value. ('''''1.4.2+''''')<br />
|-<br />
| {CUBEROOT} || Take the cube root of the running value. ('''''1.4.2+''''')<br />
|-<br />
| {CUBE} || Cube the running value. ('''''1.4.2+''''')<br />
|-<br />
| {SIN} || Return the SIN of running value. ('''''1.4.2+''''')<br />
|-<br />
| {COS} || Return the COS of running value. ('''''1.4.2+''''')<br />
|-<br />
| {TAN} || Return the TAN of running value. ('''''1.4.2+''''')<br />
|-<br />
| {ASIN} || Return the ASIN of running value. ('''''1.4.2+''''')<br />
|-<br />
| {ACOS} || Return the ACOS of running value. ('''''1.4.2+''''')<br />
|-<br />
| {ATAN} || Return the ATAN of running value. ('''''1.4.2+''''')<br />
|}<br />
<br />
<br />
'''''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 <nowiki>[[ ]]</nowiki> 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.<br />
<br />
'''''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.<br />
<br />
'''Rolling on Rollable Tables'''<br />
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.<br />
<br />
''Roll Variable Lines do not produce output lines on the card.''<br />
<br />
=== String Variable Assignment (--&) ===<br />
<br />
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:<br />
<br />
<pre><br />
--&MyText|Hello<br />
</pre><br />
<br />
Here, we assign the text "Hello" to the string variable named MyText. You can also append text to a string variable by prefixing the content with a + sign:<br />
<br />
<pre><br />
--&MyText|+ World<br />
</pre><br />
<br />
If run after the statement above, MyText will now contain "Hello World".<br />
<br />
String variables can be referenced using the syntax [&variablename]<br />
<br />
=== Call API (--@) ===<br />
<br />
ScriptCards can use a Call API instruction to execute other API commands. The Tag contains the API 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 API command is executed.<br />
<br />
Examples:<br />
<pre><br />
--@eh|list<br />
--@alter|_target|@{target|token_id} _bar|3 _amount|-[$Damage]<br />
</pre><br />
<br />
In the first example above, the command <code>!eh list</code> will be executed, calling [[EncounterHelper]]. In the second, {{fpl|1216260/ AlterBars}} is called to modify a token's Bar 3 value.<br />
<br />
'''''Note:''''' When ScriptCards (or any API script) runs other API 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).<br />
<br />
See [[API:Script Index]] for more options.<br />
<br />
=== Branch Label (--:) ===<br />
<br />
A branch label defines a line in your code that can be reached by one of the branching instructions (<nowiki>--^</nowiki>, <nowiki>--></nowiki>, or <nowiki>--?</nowiki>). The Tag serves as the label name, and must be unique on the card.<br />
<br />
The vertical bar (|) separator must be present, but the content portion of the line is unused and can be treated as a comment.<br />
<br />
Examples:<br />
<pre><br />
--:MyLoop|<br />
--:CriticalHit|Will jump here if we roll a critical hit!<br />
</pre><br />
<br />
''A Branch Label line does not produce an output line on the card.''<br />
<br />
=== Branch (--^) === <br />
<br />
A Branch line 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.<br />
<br />
Examples:<br />
<pre><br />
--^MyLoop|Jumps to MyLoop<br />
--^SkipCrit|We didn't crit, so skip the Crit code<br />
</pre><br />
<br />
''A Branch line does not produce an output line on the card.''<br />
<br />
=== Call Procedure (-->) ===<br />
<br />
Similar to a branch, a Call Procedure (sometimes knows 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 (<nowiki>--<</nowiki>) 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 (;).<br />
<br />
Examples:<br />
<pre><br />
-->FixFormat|#3333FF;#999999<br />
</pre><br />
<br />
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%].<br />
<br />
=== Return (--<) ===<br />
<br />
A return instruction marks the end of a Gosub procedure. 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.<br />
<br />
Examples:<br />
<pre><br />
--<|<br />
--<|End of MySub<br />
</pre><br />
<br />
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.<br />
<br />
=== Conditional Statement (--?) ===<br />
<br />
A conditional statement contains some equation in the Tag that will be evaluated. '''''If any part of the comparison can/does contain a space, it needs to be surrounded by double quotes'''''<br />
<br />
Based on the true/false result of the evaluation, one of two execution paths will be taken. These execution paths are detailed in the content section of the statement. The "if true" path is specified first (directly after the vertical bar), and the "if false" path is specified after it, also separated by a vertical bar.<br />
<br />
Example:<br />
<pre><br />
--?[$AttackRoll.Total] -ge [$TargetAC]|Hit|Miss<br />
</pre><br />
<br />
'''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.'''<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Branch Format !! Meaning<br />
|-<br />
| Label || If just a label is specified, execution will branch to that label when the comparison is matched.<br />
|-<br />
| >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 <br />
|-<br />
| =VariableName || The roll variable "VariableName" will be assigned the value following a semicolon (ex: --?1 -eq 1|=Roll;1d20)<br />
|-<br />
| &VariableName || The string variable "VariableName" will be assigned the value following a semicolon (ex: --?1 -eq 1|&Result;Hit|&Result;Miss)<br />
|-<br />
| % or %! || The current for...next loop will perform the "next" action (%) or will break out (%!) <br />
|-<br />
| [ || Code block (see below)<br />
|}<br />
<br />
Examples:<br />
<pre><br />
--?[$AttackRoll.Base] -eq 20|CriticalHit<br />
--?[$AttackRoll.Base] -eq 1|>Fumble;@{selected|dexterity_mod}<br />
--?"@{target|npc_type}" -inc "undead"|&MonsterType;Undead|&MonsterType;Not Undead<br />
--?[$Attack.Total] >= [$ArmorClass]|>Hit|>Miss<br />
</pre><br />
<br />
In the first example, if the Base value of AttackRoll is a 20 (natural 20 on the die) execution will branch to the CriticalHit label.<br />
<br />
In the second example, 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%].<br />
<br />
The third example looks for the word "undead" in the npc_type attribute of the targeted character. If it exists in the text, the MonsterType string variable will be set to "Undead", otherwise it will be set to "Not Undead". <br />
<br />
The final example would call 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.<br />
<br />
''Text that does/may contain a space should be enclosed in double quotes.''<br />
<br />
The following comparison operators are available:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Comparator !! Meaning<br />
|-<br />
| -eq || Equal To <br />
|-<br />
| -eqi || Case insensitive Equal To <br />
|-<br />
| -ne || Not Equal To <br />
|-<br />
| -nei || Case insensitive Not Equal To <br />
|-<br />
| -gt || Greater Than <br />
|-<br />
| -ge || Greater Than or Equal To <br />
|-<br />
| -lt || Less Than <br />
|-<br />
| -le || Less Than or Equal To <br />
|-<br />
| -inc || Includes (text strings). <br />
|-<br />
| -ninc || Does Not Include (text strings). <br />
|}<br />
<br />
Multi-part conditionals are supported with -and and -or as separators. For example:<br />
<br />
<pre><br />
--?[$Attack.Total] -ge @{target|npc_ac} -and [$Attack.Base] -ne 20|HitButNotCrit<br />
</pre><br />
<br />
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):<br />
<br />
true AND false OR true<br />
<br />
Will be evaluated as true. The first two (true and false) will be false, but then false OR true will be true.<br />
<br />
Conversely:<br />
<br />
true or false and false<br />
<br />
Will be false, because the first true and false will evaluate to true, and then true and false will be false.<br />
<br />
'''CODE BLOCKS'''<br />
<br />
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.<br />
<br />
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:<br />
<br />
<pre><br />
!script {{<br />
--=Roll|1d2<br />
--+Roll|[$Roll]<br />
--?[$Roll.Total] -eq 2|[<br />
--&Value|Yep!<br />
--+|We are inside the TRUE portion of the block<br />
--]|[<br />
--&Value|Nope<br />
--+|We are inside the FALSE portion of the block<br />
--]|<br />
--+After|the blocks!<br />
--+Value|[&Value]<br />
}}<br />
</pre><br />
<br />
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 --]|. <br />
<br />
At this time, blocks cannot be nested, and can only be created as part of a conditional (--[ is not a valid statement type)<br />
<br />
''A conditional statement does not produce a line of output on the card.''<br />
<br />
=== Case Statement (--c) ===<br />
<br />
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 (:). Each match condition includes a branch label that will be used if the test value matches the item. 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:<br />
<br />
<pre><br />
!script {{<br />
--#title|Case Statement Testing<br />
--=Roll|1d4<br />
--C[$Roll.Total]|1:>One;[$Roll]|2:>Two;[$Roll]|3:>Three;[$Roll]|4:>Four;[$Roll]<br />
--X|<br />
<br />
--:One| --+Value|was One ([%1%]) --<|<br />
--:Two| --+Value|was Two ([%1%]) --<|<br />
--:Three| --+Value|was Three ([%1%]) --<|<br />
--:Four| --+Value|was Four ([%1%]) --<|<br />
}}<br />
</pre><br />
<br />
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 variable as a parameter.<br />
<br />
=== Save and Load (--s and --l) ===<br />
<br />
This statement pair is used to either store (--s) or load (--l) data from persistent storage. Items stored in persistent storage remain between card rolls and between Roll20 sessions. There are two types of data that can be stored: settings and roll variables. <br />
<br />
Examples:<br />
<br />
<pre><br />
--Ssettings|GreenStyle<br />
--Srollvariables|FirstCardVars<br />
</pre><br />
<br />
In this case, the tag for the statement determines what type of item is being saved (settings or rollvariables). When saving settings, all non-default settings are written to the named setting storage value. When Roll Variables are saved, all variables that currently exist will be saved to the named storage value.<br />
<br />
Loading stored items simply requires the same command with the --l statement type:<br />
<br />
<pre><br />
--Lsettings|GreenStyle<br />
--Lrollvariables|FirstCardVars<br />
</pre><br />
<br />
When loading settings, all stored settings will be applied to the current card settings. You can override settings by changing them after the load.<br />
<br />
When loading roll variables, the saved variables will be added to (or overwrite if they have the same name) any variables on the current card. This means it is safe to create roll variables before the load statement.<br />
<br />
'''Practical Uses'''<br />
The major intended use of persistent storage is for storing card formats for use in later scripts. For example, the following script:<br />
<br />
<pre><br />
!scriptcard {{<br />
--#titlecardbackground|#22CC22<br />
--#oddrowbackground|#cceecc<br />
--#evenrowbackground|#99ee99<br />
--Ssettings|@{selected|token_name}<br />
}}<br />
</pre><br />
<br />
Would save the titlecardbackground, oddrowbackground, and evenrowbackground settings to a saved list named after the selected token's name. When creating cards for that token to run later, you could include the line:<br />
<br />
<pre><br />
--Lsettings|@{selected|token_name}<br />
</pre><br />
<br />
To load all of the settings at once. By creating these setting sets for each character, you can specify a different color scheme for each character that can then be used in cards with a single formatting line.<br />
<br />
There is a supplemental ! command added to support saved settings:<br />
<br />
<pre><br />
!sc-liststoredsettings<br />
</pre><br />
<br />
Will produce a list of all stored setting names, with buttons to list the setting values stored in each group and a button to delete groups as needed.<br />
<br />
=== Visual Effects (--v) ===<br />
<br />
The --v statement can be used to create visual effects on the tabletop. The tag portion of the statement can be either "token" or "betweentokens". The content portion of the statement contains the required parameters for the effect generation, separated by spaces. If the effect is "none", no effect will be played. If any other value that doesn't match a Roll20 effect name will result in a burst-fire effect.<br />
<br />
For "token" effects, the parameters are the token id for the token the effect happens on, followed by the effect specifier.<br />
<br />
Example:<br />
<pre><br />
--vtoken|@{selected|token_id} burst-fire<br />
</pre><br />
<br />
For "betweentoken" effects, the parameters are the source token id, the target token id, and the effect specifier.<br />
<br />
Example:<br />
<pre><br />
--vbetweentokens|@{selected|token_id} @{target|token_id} beam-magic<br />
</pre><br />
<br />
'''''Version 1.2.8+'''''<br />
<br />
An additional effect specifier, "point" is available in 1.2.8+. This specifier allows you to create a visual effect at a designated X/Y pixel coordinate. Future updates will add custom-vfx support to this option. The parameters are the X and Y coordinates and the effect descriptor. As of version 1.2.9, you can also use custom effect specifiers with Point effects:<br />
<br />
<pre><br />
--vpoint|150 200 burst-fire<br />
</pre><br />
<br />
=== Echo to Chat (--e) ===<br />
<br />
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.<br />
<br />
Example:<br />
<pre><br />
--eThe Ghost|/em hovers around @{selected|character_name}... BOO!<br />
</pre><br />
<br />
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).<br />
<br />
'''''Whispering'''''<br />
<br />
You can use the echo statement to send a whisper, but there's a trick to it. If you execute this code here:<br />
<br />
<pre><br />
--eThe Ghost|/w ExamplePlayerName Boo.<br />
</pre><br />
<br />
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.<br />
<br />
So, in conclusion, it's best to use something like this when you're sending a whisper:<br />
<br />
<pre><br />
!script {{<br />
--#hidecard|1<br />
--&sender|The Ghost<br />
--&receiver|ExamplePlayerName<br />
--&message|Boo.<br />
--e[&sender]|/w [&receiver] [&message]<br />
--eScriptCards|/w gm **Whispered from [&sender] to [&receiver]:** [&message] <br />
}}<br />
</pre><br />
<br />
This will ensure that the message appears in your chat feed as well.<br />
<br />
=== Repeating Section Access (--R) ===<br />
<br />
ScriptCards (as of v0.0.13) supports accessing repeating section rows on a character sheet (for example: the attacks, the items, and the repeating resources) with the --R statement type. <br />
<br />
There are three basic commands you can use with --R, and they are specified by <br />
the tag used:<br />
<br />
<br />
'''''The "find" tag'''''<br />
<br />
An Rfind statement is used to search through a repeating field. Here is the general form of such a statement.<br />
<br />
<pre><br />
--Rfind|characterid;EntryName;SectionPrefix;SearchField<br />
</pre><br />
<br />
This is the most direct way to access a repeating section row. Supplying the character ID, followed by what you are looking for (Greatsword, for example), followed by the character sheet's section prefix (repeating_attack), followed by the field to check what you are searching for (atkname) will load the matching section (if found) into the script parsers memory. For example:<br />
<br />
<pre><br />
--Rfind|@{selected|character_id};Greatsword;repeating_attack;atkname<br />
</pre><br />
<br />
Will look at the character's "repeating_attack" section for an entry with an atkname value equal to "Greatsword". Similarly:<br />
<br />
<pre><br />
--Rfind|@{selected|character_id};Bite;repeating_npcaction;name<br />
</pre><br />
<br />
Will look for a "Bite" action on an NPC's action list.<br />
<br />
<br />
'''''The "first" tag'''''<br />
<br />
<pre><br />
--Rfirst|characterid;section prefix<br />
</pre><br />
<br />
This form of the --R command will look at all of the entries in the specified repeating section and load the first one into memory:<br />
<br />
<pre><br />
--Rfirst|@{selected|character_id};repeating_attack<br />
</pre><br />
<br />
Would load the character's first "repeating_attack" row into memory.<br />
<br />
<br />
'''''The "next" tag'''''<br />
<br />
<pre><br />
--Rnext|<br />
</pre><br />
<br />
No parameters are required for --Rnext, which loads the next entry in the list that was obtained with "first" into memory.<br />
<br />
<br />
'''''Section prefixes and how to use them'''''<br />
<br />
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 open [[D&D 5E by Roll20|this page]], and search for the phrase "repeating sections".<br />
<br />
<br />
'''''Additional information'''''<br />
<br />
However a row is obtained, it will be parsed to replace any attribute references (ie, @{level}) with the corresponding character attribute.<br />
<br />
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".<br />
<br />
You can reference repeating attribute data using the syntax [*R:attributename] syntax (similar to referencing standard character attributes).<br />
<br />
Here are some examples:<br />
<br />
Display the details of the "Greatsword" PC attack:<br />
<br />
<pre><br />
!script {{<br />
--Rfind|@{selected|character_id};Greatsword;repeating_attack;atkname<br />
--+Attack Name|[*R:atkname]<br />
--+Base Damage|[*R:dmgbase]<br />
}}<br />
</pre><br />
<br />
[[File:Scriptcards repeating greatsword.png|Repeating Greatsword Attack]]<br />
<br />
List all of the actions an NPC can take (just actions, not legendary, etc.)<br />
<br />
<pre><br />
!script {{<br />
--#title|NPC Actions<br />
--#leftsub|@{selected|token_name}<br />
--Rfirst|@{selected|character_id};repeating_npcaction<br />
--:DisplayLoop|<br />
--?"[*R:name]" -eq NoRepeatingAttributeLoaded|Done<br />
--+Action:|[*R:name] [*R:attack_damage] [*R:attack_damagetype]<br />
--?"[*R:attack_damage2]" -eq ""|NoSecondaryDamage<br />
--+ |[*R:attack_damage2] [*R:attack_damagetype2]<br />
--:NoSecondaryDamage|<br />
--Rnext|<br />
-->DisplayLoop| <br />
--:Done|<br />
}}<br />
</pre><br />
<br />
[[File:Scriptcards repeating npcactions.png]]<br />
<br />
In the script above, we get the "first" repeating_npcaction and display information about it. We then execute "next" and repeat until we run into "NoRepeatingAttributeLoaded".<br />
<br />
See the section named [[#Repeating Section Values|Repeating Section Values]] for more information.<br />
<br />
<br />
'''''Special debugging command: dump'''''<br />
<pre><br />
--Rdump|<br />
</pre><br />
<br />
The "dump" command will list all of the attributes ScriptCards knows about for the currently loaded repeating row to the API Console Log.<br />
<br />
=== Assign Variable to Built-In Function (--~) ===<br />
<br />
ScriptCards has the ability to run a function built into the API script and return the results to a variable. Some functions return roll variables, while others return strings. See the function table below for details. The format is:<br />
<br />
--~VariableName|function;param1;param2;param3;...<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Function Name !! Parameters !! Description<br />
|-<br />
| distance || token_A_ID;token_B_ID || Calculate the Chebyshev distance in grid units between two tokens. This is the measurement scheme D&D 4E/5E use for diagonal distance measurement<br />
|-<br />
| euclideandistance || token_A_ID;token_B_ID || Calculate the Euclidean distance between two tokens. This is essentially the Pythagorean theorem in action. Returns the result in grid units.<br />
|-<br />
| euclideanpixel || token_A_ID;token_B_ID || Calculate the Euclidean distance between two tokens and returns the result is pixels instead of grid units. <br />
|-<br />
| euclideanlong || token_A_ID;token_B_ID || 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 is calculated instead of before. More accurate over long distances. <br />
|-<br />
| manhattandistance || token_A_ID;token_B_ID || Also called "taxicabdistance" (which is an acceptable function name), this measures to how-many-over, how-many-up/down distance, disallowing diagonal movement.<br />
|-<br />
| getselected || none || 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 the first selected token, VariableName2 the second, etc.<br />
|}<br />
<br />
'''''Functions with Sub Functions'''''<br />
<br />
Most ScriptCards functions are grouped into set as sub functions. The table below lists the major functions and their sub functions.<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Function Name !! Sub Function !! Parameters !! Return Type !! Description<br />
|-<br />
| array || define || arrayname;value1;value2;... || none || Creates an array called "arrayname" and adds value1, value2, etc. to the array<br />
|-<br />
| array || sort || arrayname || none || Sorts the specified array in place in ascending order<br />
|-<br />
| array || add || arrayname;value1;value2;... || none || Adds value1, value2, ... to the existing array "arrayname"<br />
|-<br />
| array || remove || arrayname;value1;value2;... || none || Removes value1, value2, ... from the existing array "arrayname". Resets the array index to 0.<br />
|-<br />
| array || replace || arrayname;currentvalue;newvalue || none || Replaces all occurrences of "currentvalue" in "arayname" with "newvalue"<br />
|-<br />
| array || setatindex || arrayname;index;newvalue || none || Replaces the array item at index "index" with "newvalue"<br />
|-<br />
| array || getindex || arrayname || stringVariable || Retrieves the current index in "arrayname" and stores it in the supplied string variable<br />
|-<br />
| array || setindex || arrayname;newindex || none || Sets the current index in array "arrayname" to "newindex"<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| array || removeat || arrayname;indexposition || none || Removes the item at index "indexposition" from "arrayname". Resets the current array index to 0.<br />
|-<br />
| array || indexof || arrayname;searchvalue || stringVariable || Searches the array "arrayname" for and item with the value of "searchvalue" and, if found, returns the index of the first matching value or "ArrayError" if not found<br />
|-<br />
| array || getlength || arrayname || stringVariable || Returns the number of items in array "arrayname"<br />
|-<br />
| array || pagetokens || arrayname;tokenid;(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. 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.)<br />
|-<br />
| 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.<br />
|-<br />
| array || stringify || arrayname || stringVariable || Returns all of the items in "arrayname" as a string separated by semicolons (;)<br />
|-<br />
| array || fromstring || arrayname || delimiter;string || Creates an array from "string", splitting "string" on "delimiter" to separate the items<br />
|-<br />
| array || statusmarkers|| arrayname;tokenid || none|| Creates an array (arrayname) of the active statusmarkers (sometimes called Token Markers) for the specified tokenid<br />
|-<br />
| math || angle || math;angle;tokenid;tokenid|| rollVariable || Calculates the angle between two tokens and returns the value in degrees<br />
|-<br />
| math || ceil || math;ceil;value || rollVariable || Rounds '''value''' up to the next integer, dropping any decimal portion of the number<br />
|-<br />
| math || clamp || math;clamp;value;lowerBound;upperBound || rollVariable || Returns '''value''', but restricted to the range of '''loweBound''' and '''upperBound'''.<br />
|-<br />
| math || floor || math;floor;value || rollVariable || Rounds '''value''' down, dropping any decimal portion of the number<br />
|-<br />
| math || max || math;max;valueA;valueB || rollVariable || Returns the larger of '''valueA''' vs '''valueB'''<br />
|-<br />
| math || min || math;min;valueA;valueB || rollVariable || Returns the smaller of '''valueA''' vs '''valueB'''<br />
|-<br />
| math || round || math;round;value || rollVariable || Rounds '''value''' to the nearest integer<br />
|-<br />
| string || length || string;length;stringValue || rollVariable || Returns the length of '''stringValue''' in characters<br />
|-<br />
| string || before || string;before;searchText;stringValue || stringVariable || Searches '''stringValue''' for '''searchText''' and returns the portion of '''stringValue''' prior to that text<br />
|-<br />
| string || after || string;after;searchText;stringValue || stringVariable || Searches '''stringValue''' for '''searchText''' and returns the portion of '''stringValue''' after that text<br />
|-<br />
| string || left || string;left;count;stringValue || stringVariable || Returns the leftmost '''count''' characters of '''stringValue'''<br />
|-<br />
| string || right || string;right;count;stringValue || stringVariable || Returns the rightmost '''count''' characters of '''stringValue'''<br />
|-<br />
| string || replace || string;replace;searchText;replaceText;stringValue || stringVariable || Replaces '''searchText''' in '''stringValue''' with '''replaceText''' and returns the resulting string<br />
|-<br />
| string || replaceall || string;replace;searchText;replaceText;stringValue || stringVariable || Replaces all intances of '''searchText''' in '''stringValue''' with '''replaceText''' and returns the resulting string '''''Requires 1.2.9+'''''<br />
|-<br />
| string || trim || string;trim;stringValue || stringVariable || Removes leading and trailing spaces from stringValue and returns the result. <br />
|-<br />
| string || substring || string;substring;start;count;stringValue || stringVariable || Returns '''count''' characters starting at '''start''' from '''stringValue'''<br />
|-<br />
| 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.<br />
|-<br />
| string || tolowercase || string;tolowercase;stringValue || stringVariable || Converts the passed string to lower case and assigns to the passed variable name. <br />
|-<br />
| string || touppercase || string || stringVariable || Converts the passed string to upper case and assigns to the passed variable name. <br />
|-<br />
| 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. <br />
|-<br />
| 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.<br />
|-<br />
| 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'''.<br />
|-<br />
| turnorder || clear || none || none || Clears all entries from the {{Turn Tracker}}/Initiative<br />
|-<br />
| turnorder || addtoken || tokenid;trackervalue || none || Adds the token represented by "tokenid" to the initiative tracker with an initiavie value of "trackervalue"<br />
|-<br />
| turnorder || replacetoken || tokenid;trackervalue || none || Replaces the token represented by "tokenid" in the initiative tracker with an initiavie value of "trackervalue". Will add the token if it doesn't exist in the tracker.<br />
|-<br />
| turnorder || removetoken || tokenid || none || Removes the token represented by "tokenid" from the initiative tracker if it exists<br />
|-<br />
| turnorder || addcustom || textlabel;trackervalue || none || Add a custom text entry to the {{Turn Tracker}}/Initiative named "textlabel" with an initiative value of "trackervalue"<br />
|-<br />
| system || date || getdatetime || stringVariable || Returns the date time in the active timezone (see settings) <br />
|-<br />
| system || date || getdate || stringVariable || Returns the date in the active timezone (see settings) <br />
|-<br />
| system || date || gettime || stringVariable || Returns the time in the active timezone (see settings)<br />
|-<br />
| system || dumpvariables || "rolls", "string", or "array" || none || Dumps all of the defined variables of the indicated type to the console log<br />
|-<br />
| system || findability || system;findability;charactername;abilityname || stringVariable || Returns the object ID of the ability on the indicated character or "AbilityNotFound"<br />
|-<br />
|}<br />
<br />
Examples:<br />
<br />
<pre><br />
--~HowFarAway|distance;@{selected|token_id};@{target|token_id}<br />
</pre><br />
<br />
Returns the distance (Chebyshev) between the selected and target tokens and stores it in "HowFarAway".<br />
<br />
<pre><br />
--SelectedDudes|getselected<br />
</pre><br />
<br />
If 5 tokens were selected, 6 variables would be created: SelectedDudesCount (with a value of 5), SelectedDudes1, SelectedDudes2, SelectedDudes3, SelectedDudes4, SelectedDudes5.<br />
<br />
=== Information Request (--i) ===<br />
<br />
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.<br />
<br />
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.<br />
<br />
After the user has clicked the button and responded to the requests, ScriptCards will resume processing the script from where it left off.<br />
<br />
Here is an example “i” line:<br />
<br />
<pre><br />
--IScriptCards needs additional information to continue;Click to select a target and provide information|t;MyNewTarget;Missile1Target||q;MyNameIs;What is your name?<br />
</pre><br />
<br />
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.<br />
<br />
Supported information request types are “t” for target token, and “q” for query.<br />
<br />
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).<br />
<br />
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:<br />
<br />
<pre><br />
q;UserName;What is your name?|Fred|Bob|Sally|Nancy<br />
</pre><br />
<br />
Would have a dropdown menu with four choices.<br />
<br />
== Inline Formatting ==<br />
<br />
Inline formatting is processed on Direct Output lines only (--+ lines) and the following inline format markup is available:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Formatting Tags !! Description<br />
|-<br />
| [b]..[/b] || Bold the text between the markers <br />
|-<br />
| [i]..[/i] || Italicize the text between the markers <br />
|-<br />
| [u]..[/u] || Underline the text between the markers <br />
|-<br />
| [s]..[/s] || Strike-Thru the text between the markers <br />
|-<br />
| [c]..[/c] || Center alignment <br />
|-<br />
| [l]..[/l] || Left alignment <br />
|-<br />
| [r]..[/r] || Right alignment <br />
|-<br />
| [j]..[/j] || Full justification alignment <br />
|-<br />
| [#xxx]..[/#] or [#xxxxxx]..[/#] || Use a 3 or 6 digit hex code to colorize the text between the markers <br />
|-<br />
| [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, <code>[img width=128 height=128]</code> )<br />
|-<br />
| [button]caption::action[/button] || Create a button with the label "caption" that performs the action defined by "action". <br />
|-<br />
| [t] || Converted to HTML table tag. Text after the "t" will be included inside the tag (width, border, etc)<br />
|-<br />
| [/t] || Converted to HTML close table tag.<br />
|-<br />
| [tr] || Converted to HTML table row tag. Text after the "tr" will be included inside the tag<br />
|-<br />
| [/tr] || Converted to HTML close table row tag.<br />
|-<br />
| [td] || Converted to HTML table cell tag. Text after the "tr" will be included inside the tag<br />
|-<br />
| [/td] || Converted to HTML close table cell tag.<br />
|}<br />
<br />
== Variables ==<br />
<br />
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. While it is possible to assign both a string and a roll variable the same name, doing so will likely result in confusion when looking at the script later, so it is not recommended.<br />
<br />
String Variables are assigned with the --& statement and are referenced using [&variableName] notation.<br />
<br />
Roll Variables are assigned with the --= statement, and the assignment value is always processed by the ScriptCards Roll Processor (resolves dice rolls, etc.)<br />
<br />
There are a handful of variables assigned automatically when a ScriptCard is executed. These are all string variables, and are:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Variable !! Value<br />
|-<br />
| SendingPlayerID || Contains the object ID of the player that sent the macro<br />
|-<br />
| SendingPlayerName || Contains the display name of the player<br />
|-<br />
| SendingPlayerColor || Contains the color code associated with the player<br />
|-<br />
| SendingPlayerSpeakingAs || The contents of the "Speaking As" dropdown window<br />
|-<br />
| SendingPlayerIsGM || Contains 1 if the player is a GM, and 0 if the player is NOT a GM<br />
|}<br />
<br />
== Arrays ==<br />
<br />
Arrays are a special type of variable, and are managed by the function (<nowiki>--~</nowiki> command). All of the array function commands follow the same pattern:<br />
<br />
<pre>--~variableName|array;subcommand;arrayname;param1;param2;param3;...</pre><br />
<br />
Not all array commands return anything to "variableName". The function table above will specify the return type of the command if any.<br />
<br />
There are a couple of different ways to create an array:<br />
<br />
The '''define''' array subcommand creates (or recreates) an array and assigns it values - one for each included parameter after the array name. For example:<br />
<br />
<pre>--~|array;define;Fruits;mango;peach;strawberry;apricot;banana;apple</pre><br />
<br />
will create an array called '''Fruits''' with 6 elements in the order listed in the command (mango, peach, etc.)<br />
<br />
You can also use two other subcommands to create arrays based on tokens:<br />
<br />
<pre>--~Count|array;pagetokens;Everybondy;@{selected|token_id}</pre><br />
<br />
and<br />
<br />
<pre>--~Count|array;selectedtokens;Selected</pre><br />
<br />
In both cases, arrays of tokens will be created, and a string variable called "Count" will be set to the number of tokens in the array. The '''pagetokens''' command returns (by default) all of the tokens on the page that contains the token passed as the parameter after the array name. You can filter the tokens that "pagetokens" includes in the array by appending an optional parameter describing the type of token you are looking for:<br />
<br />
<pre>--~Count|array;pagetokens;Everybondy;@{selected|token_id};npc</pre><br />
<br />
Will return only tokens on the page that represent characters that do not have a ''controlledby'' parameter set. The available options are "all" (default), "char", "graphic", "pc", and "npc".<br />
<br />
The '''selectedtokens''' command returns an array with all of the tokens that were selected when the script was called.<br />
<br />
You can also use an arbitrary string to create an array, specifying a delimiter with the '''fromstring''' command:<br />
<br />
<pre><br />
--&names|Fred<br />
--&names|+,Sally<br />
--&names|+,Ted<br />
--&names|+,Joyce<br />
--~|array;fromstring;,;[&names]<br />
</pre><br />
<br />
The above example builds a comma-separated string and then uses "fromstring" to create an array with 4 elements from it, specifying the comma as the delimiter.<br />
<br />
Finally, you can use the '''statusmarkers''' command to create an array with one entry for each active status marker on a specified token:<br />
<br />
<pre>--~|array;statusmarkers;Conditions;@{selected|token_id}</pre><br />
<br />
will create an array with one entry for each status active on the selected token. The array elements will be the internal name of the status (if you are using custom status marker packs, the names will be specified in the marker pack).<br />
<br />
'''Traversing Arrays'''<br />
<br />
Each array keeps track of an internal index position (starting at 0). Several commands let you manage this index:<br />
<br />
*'''getindex''' returns the current index value<br />
*'''setindex''' sets the index to the specified location in the array<br />
*'''getlength''' returns the number of elements in the array<br />
*'''indexof''' returns the index location of the specified element<br />
<br />
Other commands let you retrieve values from the array:<br />
<br />
*'''getfirst''' sets the index to 0 and returns the value at that position<br />
*'''getnext''' advances the index by 1 and returns the new current value<br />
*'''getprevious''' reduces the index by 1 and returns the new current value<br />
*'''getlast''' sets the index to the last elements in the array and returns the new current value<br />
<br />
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.<br />
<br />
'''Manipulating Array Elements'''<br />
<br />
Several array commands deal with inserting, removing, and modifying elements:<br />
<br />
*'''add''' works just like define, except that it takes an existing array and adds elements to it based on the passed parameters<br />
*'''remove''' looks for items matching each passed parameter and removes them from the indicated array if they exist<br />
*'''removeat''' allows you to specify an index location in the array and remove the element at that position<br />
*'''replace''' searches an array for a value and replaces all occurrences of it with a new value (if found)<br />
*'''sort''' sorts the elements in the array in ascending order<br />
*'''strinfigy''' returns a string variable that includes each array element separated by semicolons (;) <br />
<br />
'''Referencing Array Elements'''<br />
<br />
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.<br />
<br />
<pre><br />
!script {{<br />
--~dummy|array;pagetokens;myarray;@{selected|token_id}<br />
--~count|array;getcount;myarray<br />
--+Total:|There are [&count] graphical objects on the page<br />
--~testvar|array;getfirst;myarray<br />
--:loop|<br />
--+Value|[*[&testvar]:character_name]<br />
--~testvar|array;getnext;myarray<br />
--?[&testvar] -ne ArrayError|loop<br />
--+Loop1|Is Done!<br />
}}<br />
</pre><br />
<br />
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:<br />
<br />
<pre><br />
!script {{<br />
--~dummy|array;pagetokens;myarray;@{selected|token_id}<br />
--~count|array;getcount;myarray<br />
--+Total:|There are [&count] graphical objects on the page<br />
--%loopCounter|1;[&count]<br />
--+Value|[*[@myarray([&loopCounter])]:character_name]<br />
--%|<br />
--+Loop|Is Done!<br />
}}<br />
</pre><br />
<br />
This line : <nowiki>--+Value|[*[@myarray([&loopCounter])]:character_name]</nowiki> uses [@arrayName(index)] format (inside a [*characterid:attribute] syntax) to perform the same task as running through the loop with the index.<br />
<br />
(Note: Additional examples are on the way...)<br />
<br />
== For...Next Loops ==<br />
<br />
For...Next loops in ScriptCards are supported with the with the --% statement type. A loop is defined by starting off with:<br />
<br />
<pre><br />
--%LoopCounter|<start>;<end>;[step]<br />
</pre><br />
<br />
The start and end values are required, while the step parameter is optional. If the step is omitted, it will be assumed to be 1. A string variable named after the line tag ("LoopCounter" in the case above) will be created and will hold the current iteration value for the loop. Here is a real example:<br />
<br />
<pre><br />
--%LoopCounter|1;10;1<br />
</pre><br />
<br />
This will begin a loop identified by "LoopCounter" that will start at 1, increasing by 1 each iteration (the step) until it has completed 10 executions.<br />
<br />
The "next" statement is simply <code>--%|</code>, with no tag or parameters. This indicates to ScriptCards that it should increment the counter and go back to the beginning of the loop. Extending the example above:<br />
<br />
<pre><br />
!script {{<br />
--%LoopCounter|1;10;1<br />
--=Roll|1d20<br />
--+Loop|Counter is [&LoopCounter], roll was [$Roll]<br />
--%|<br />
}}<br />
</pre><br />
<br />
The <code>--%!|</code> sequence will break out of the loop, no matter how many iterations are remaining.<br />
<br />
The % and %! character sequences can also be used as part of a 1.2.1+ non-branching conditional to continue or break the loop:<br />
<br />
<pre><br />
--?"X[&RollInto]X" -eq "XX"|%<br />
</pre><br />
<br />
In this example, if the string variable RollInfo is empty, the loop will return to the top and continue with the next iteration, while:<br />
<br />
<pre><br />
--?"X[&RollInto]X" -eq "XX"|%!<br />
</pre><br />
<br />
Would cause the whole loop to end if the condition were true.<br />
<br />
== Referencing ==<br />
<br />
=== Roll Variables===<br />
<br />
Roll Variables can be referenced from the content portion of any line type, and from the tag portion of conditional statements. The referenced value is replaced when the line is executed.<br />
<br />
There are several modifiers that can be used to reference parts of a roll:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Modifier !! Meaning<br />
|-<br />
| No modifier || In a Direct Output Line (<nowiki>--+</nowiki>), GM Output Line (<nowiki>--*</nowiki>), or String Assignement (<nowiki>--&</nowiki>), 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<br />
|-<br />
| .Total || The end result of the roll equation. Formatting rules for "No Modifier" apply based on line type. <br />
|-<br />
| .Raw || The total value of the roll variable without any formatting, no matter what kind of line the reference is used in.<br />
|-<br />
| .Base || The cumulative result of any dice rolled in the Roll Text (Numeric modifiers are not included) <br />
|-<br />
| .Ones || The number of dice in the roll that came up as 1s <br />
|-<br />
| .Aces || The number of dice in the roll that came up as the maximum number on the die <br />
|-<br />
| .Odds || The number of dice in the roll that came up with an odd number <br />
|-<br />
| .Evens || The number of dice in the roll that came up with an even number <br />
|-<br />
| .RollText || The raw text of the roll that was use to generate the results <br />
|-<br />
| .Text || A text representation of the results of the roll, including the numbers rolled for each die <br />
|-<br />
| .tableEntryText || The text portion of the result of a table roll<br />
|-<br />
| .tableEntryImgURL || The image source portion of the result of a table roll<br />
|-<br />
| .tableEntryValue || If the tableEntryText is purely numeric, will contain the numeric value<br />
|}<br />
<br />
=== String Variables ===<br />
<br />
To reference a string variable, use the notation [&variablename]. String variables can be referenced in direct output, roll variable assignment, and string variable assignment statements.<br />
<br />
=== Character/Token Attributes ===<br />
<br />
A character or token attribute can be referenced from content portion of any type of line and is substituted when the line is executed. The general format for referencing a character attribute is [*ID:attribute]. ID can be a token ID or a character ID (these start with a dash). Additionally if you have specified a sourceToken or targetToken, you can substitute "S" or "T" for the ID (for example [*S:npc_type] will retrieve the npc_type attribute from the source token.<br />
<br />
By default, all attribute references will be pulled from the '''''character''''' object that the ID represents (either directly or by being a Token ID that represents a character).<br />
<br />
Keep in mind, that if you want to access the "max" of a character attribute (for example, the max hit points), then you cannot trust the name that your roll20 character sheet shows you when you hover your mouse over the max hit points. For example, this reference will not work: [*S:hp_max]. Instead, you need to use this reference: [*S:hp^].<br />
<br />
If your ID refers to a token, token attributes can be accessed by preceding the attribute name with "t-", for example [*S:t-aura1_radius]. Supported token attributes are:<br />
<br />
{|<br />
| t-name || t-id || t-statusmarkers || t-bar1_value<br />
|-<br />
| t-bar1_max || t-bar2_value || t-bar2_max || t-bar3_value<br />
|-<br />
| t-bar3_max || t-top || t-left || t-width<br />
|-<br />
| t-height || t-rotation || t-layer || t-aura1_radius<br />
|-<br />
| t-aura1_color || t-aura2_radius || t-aura2_color || t-aura1_square<br />
|-<br />
| t-aura2_square || t-tint_color || t-light_radius || t-light_dimradius<br />
|-<br />
| t-light_angle || t-light_losangle || t-light_multiplier || t-light_otherplayers<br />
|-<br />
| t-light_hassight || t-flipv || t-fliph || t-controlledby<br />
|-<br />
| t-_cardid || t-_pageid || t-imgsrc || t-bar1_link<br />
|-<br />
| t-bar2_link || t-bar3_link || t-represents || t-layer<br />
|-<br />
| t-isdrawing || t-name || t-gmnotes || t-showname<br />
|-<br />
| t-showplayers_name || t-showplayers_bar1 || t-showplayers_bar2 || t-showplayers_bar3<br />
|-<br />
| t-showplayers_aura1 || t-showplayers_aura2 || t-playersedit_name || t-playersedit_bar1<br />
|-<br />
| t-playersedit_bar2 || t-playersedit_bar3 || t-playersedit_aura1 || t-playersedit_aura2<br />
|-<br />
| t-lastmove || t-adv_fow_view_distance || t-has_bright_light_vision || t-has_night_vision<br />
|-<br />
| t-night_vision_distance || t-emits_bright_light || t-bright_light_distance || t-emits_low_light<br />
|-<br />
| t-low_light_distance || t-has_limit_field_of_vision || t-limit_field_of_vision_center || t-limit_field_of_vision_total<br />
|-<br />
| t-has_limit_field_of_night_vision || t-limit_field_of_night_vision_center || t-limit_field_of_night_vision_total || t-has_directional_bright_light<br />
|-<br />
| t-directional_bright_light_center || t-directional_bright_light_total || t-has_directional_dim_light || t-directional_dim_light_center<br />
|-<br />
| t-directional_dim_light_total || t-lightColor || || |<br />
|}<br />
<br />
'''''It is important to note that some attributes names on tokens have corresponding attribute names on characters, which represent different values. For example, [*T:id] returns the character ID, while [*T:t-id] returns the token ID.'''''<br />
<br />
=== Subroutine Parameters ===<br />
<br />
When using a gosub statement (-->) or a conditional marked as a gosub (prefixing the label with a > character), you can pass any number of parameters separated by semicolons (;) that the code in the subroutine can utilize.<br />
<br />
Subroutine parameters are numbered starting at 1, and are accessed by using the notation [%number%], so the first parameter is [%1%], the second is [%2%], etc.<br />
<br />
Parameter substitution happens on all line types, and happens prior to character attribute references or roll variable substitution.<br />
<br />
=== Campaign Attribute ===<br />
You can retrieve properties of the API's Campaign object with the [*C:attributename] syntax. For example, [*C:playerpageid] will retrieve the current player ribbon page from the Campaign object.<br />
<br />
=== Page Attributes ===<br />
If you have set the '''activepage''' parameter, you can retrieve page-related properties with the [*P:attributename] syntax, including the page's UDL parameters.<br />
<br />
=== Repeating Section Values ===<br />
<br />
You can reference repeating attribute data using the syntax [*R:attributename] syntax (similar to referencing standard character attributes). The currently active repeating row information will be used to retrieve attribute values. You can also retrieve the full attribute name for a repeating row attribute by using the [*R>attributename] notation. This is useful to pass to things like chatsetattr.<br />
<br />
See the section named [[#Repeating Section Access (--R)|Repeating Section Access]] for more information.<br />
<br />
=== Array Elements ===<br />
After an array has been declared, the elements can be referenced with [@arrayName(index)]. Array indices start at 0.<br />
<br />
== Deferred Resolution for Meta Scripts ==<br />
<br />
As of 1.2.9, ScriptCards supports a deferral character for use when calling another API script with via the --@ statement, to defer processing of meta script references so they get processed prior to the sub-API call insted of prior to ScriptCards execution. To defer this processing for meta script (SelectManager, Fetch) by inserting a deferral character into the meta call. For example, if I want to have ScriptCards call TokenMod as if the token for "Quej Gr'stra" (yes, I let Roll20 name my test NPCs) I could use something like this:<br />
<br />
--@token-mod|{^& select Quej Gr'stra} _on showname<br />
<br />
The "^" in between { and & will prevent SelectManager from seeing the call when the ScriptCard script is processed, but the --@ statement will remove the deferral character so the command that will be sent by ScriptCards is:<br />
<br />
!token-mod {& select Quej Gr'stra} --on showname<br />
<br />
With the deferral character removed, SelectManager will see the {& select ...} and do its magic.<br />
<br />
While the default deferral character is "^", the deferral character is a setting that can be changed:<br />
<br />
--#deferralcharacter|%<br />
<br />
Will make % the deferral character for future --@ statements in the running script.<br />
<br />
There are currently three supported Meta script structures: {^&...} for SelectManager, @^(...) and *^(...) for fetch, where the ^ in the structures here represents the placement of the deferral character.<br />
<br />
== Arrays ==<br />
<br />
Arrays are a new data type introduced in version 1.1.12 of ScriptCards, and are manipulated with associated function (--~) commands.<br />
<br />
* Arrays are a lists of strings. Items in an array cannot contain the semi-colon (;) character, as that is used to separate parameters in the function code that deals with arrays.<br />
* Arrays are accessed via the --~ script command. In some cases, the value of the tag (variable name) for array commands is not used, and can be a dummy value or simply omitted. I have omitted them in the statements below.<br />
* All commands that DO return a value return string values, even if the content is numeric.<br />
* If a command returns a value and there is some sort of reason that it isn't an array value, you will get "ArrayError" in the return value. This can happen if you reach the end of an array while stepping through it, for example, so checking for "ArrayError" can serve as the end condition for a loop.<br />
* Each array keeps track of its current index, allowing you to step forward and backwards through arrays.<br />
* Any number of arrays can be defined.<br />
* Unlike string variables and roll variables, array variables cannot (currently) be referenced directly. It is necessary to use the function (--~) syntax to manipulate arrays and get values from them as strings for use in other parts of your script.<br />
<br />
<br />
== Reentrant Scripts ==<br />
<br />
Reentrant scripts allow you to create buttons in your script code that will re-execute the script at a given label within the code. If you set the reentrant setting (--#reentrant|somevalue) to a non-zero value, your setting and variable information will be preserved between executions. Reentrant script can be used to present menus or choices and then continue acting.<br />
<br />
Reentrant buttons are created with the [rbutton]Caption::ReentryLabel;Parameter[/rbutton] construct. The caption will be displayed on the generated button. ReentryLabel is the name of a label in your script that the button will jump to when clicked, and Parameter will be passed in as a string value called "reentryval".<br />
<br />
Example:<br />
<pre><br />
!script {{<br />
--#reentrant|testing<br />
--=Roll|1d20<br />
--+Roll|[$Roll]<br />
--&String|That was a [$Roll.Raw]!<br />
--~x|array;define;MyArray;Apple;Banana;Orange<br />
--+Try it|[rbutton]Hello!::EXEC_PC_SPELL;9[/rbutton]<br />
--X|<br />
<br />
--:EXEC_PC_SPELL|<br />
--+ReentryVal|[&reentryval]<br />
--+The value of Roll is|[$Roll]<br />
--+Value of String|[&String]<br />
--+Array|[@MyArray(0)]<br />
--X|<br />
}}<br />
</pre><br />
<br />
This script sets up some variables and then displays a button labeled "Hello!". If the user clicks the button, the script will be re-entered starting at the "EXEC_PC_SPELL", which will display the content of the variables from the original execution.<br />
<br />
'''''Note: This section needs to be expanded upon'''''<br />
<br />
== Procedure Libraries ==<br />
<br />
You can now create handouts in your game in Roll 20 with the name format "ScriptCards Library NAME", where name is a name you assign to the library. Library names are case sensitive. It is my hope that the more proficient ScriptCards scripters out there will provide procedure libraries (or procedures that can be included in libraries) for others to use to make their scripting life easier. Be they specific to a game system, or to a type of activity, I think a robust set of libraries that GMs could use to enhance their scripting capabilities would be very valuable to the community. Should such things begin to emerge, I’ll create a portion of the ScriptCards Wiki page to house them.<br />
<br />
To include one or more libraries in a script, use the +++libname+++ directive (does not need a -- line associated with it). Multiple library names can be specified by separating them with semicolons (i.e., +++General;dnd5elib;Colorize+++ would include three libraries (General, dnd5elib, and Colorize).<br />
<br />
Included libraries are separated from the main script code by the automatic inclusion of "--X|" before the first library is appended to the script, and all libraries are loaded at the end of the script before script processing takes place.<br />
<br />
Procedures and labels in libraries can be used just as if they were included in the body of your script. Note that this DOES mean that you could, technically, jump into a library with a direct branch (--^) or direct branch conditional, but I recommend using libraries to store reusable procedures.<br />
The Notes section of the library handout stores the library code, and is written just like any other ScriptCards code except:<br />
<br />
* They cannot use roll queries (?{Some Prompt:}) to get information from the user at execution time.<br />
* They cannot use @{} notation to access character and token information.<br />
<br />
Both of these limitation stem from the fact that Procedure Libraries are not processed by the chat server, which is what handles these items.<br />
<br />
Here is an example of handling damage modifications (resistance, vulnerability, and immunity) in D&D 5E with a library:<br />
<br />
<pre><br />
!script {{<br />
+++dnd5elib+++<br />
--#|Damage Modifiers Test<br />
--#targettoken|@{target|token_id}<br />
-->Lib5E_CheckDamageModifiers|ResistType;fire<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] fire damage<br />
<br />
-->Lib5E_CheckDamageModifiers|ResistType;cold<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] cold damage<br />
<br />
-->Lib5E_CheckDamageModifiers|ResistType;poison<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] poison damage<br />
<br />
-->Lib5E_CheckDamageModifiers|ResistType;acid<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] acid damage<br />
<br />
--X|<br />
}}<br />
</pre><br />
<br />
Library content (In a handout called “ScriptCards Library dnd5elib” NOTE: Paste into Notepad first and then paste into the handout in Roll20 to avoid bringing over HTML formatting from the web site):<br />
<br />
<pre><br />
--/|ScriptCards Library: dnd5elib version 0.0.1<br />
--/|Provides various utility procedures for D&D 5E games<br />
<br />
--/|Lib5E_CheckDamageModifiers handle damage resistance, vulnerability, and immunity. <br />
--/|Pass a string variable to be filled with a string to be appended to a dice roll and the damage type <br />
<br />
--:Lib5E_CheckDamageModifiers|damageVariableName;damageType<br />
--&[%1%]|<br />
--?"[*T:npc_vulnerabilities]" -inc "[%2%]"|>_Lib5E_IsVulnerable;[%1%]<br />
--?"[*T:npc_resistances]" -inc "[%2%]"|>_Lib5E_IsResistant;[%1%]<br />
--?"[*T:npc_immunities]" -inc "[%2%]"|>_Lib5E_IsImmune;[%1%]<br />
--<|<br />
<br />
--:_Lib5E_IsVulnerable| --&[%1%]| * 2 [Vulnerable] --<|<br />
--:_Lib5E_IsResistant| --&[%1%]| \ 2 [Resistant] --<|<br />
--:_Lib5E_IsImmune| --&[%1%]| * 0 [Immune] --<|<br />
</pre><br />
<br />
The idea is that the functions in the library create a string that can be appended to a roll to modify the output based on resistances, so you pass Lib5E_CheckDamageModifiers the name of the string variable you want to use and the damage type. The variable (ResistType in this case) will include either nothing, “* 2 [Vulnerable]”, “\ 2 [Resistant]”, or “* 0 [Immune]” which can be included in a roll assignment (--=) to modify the damage as appropriate. The order here might be important if an NPC is misconfigured to be both resistant and immune to the same damage type. Since immune is an absolute, having it last ensures that it will override resistant or vulnerable. A creature that is both vulnerable and resistant (again, misconfigured) will come back as resistant since that condition is checked after vulnerable.<br />
Some notes: I prefix my library labels with either “Lib5E_” or “_Lib5E_” as a clarity convention. This isn’t strictly necessary but you should be aware that if two libraries (or if your script and a library) define the same label, the last label defined will win. Since libraries are appended to the end of the script in the order you include them in the +++libname+++ directive, you can somewhat control this, but it is probably best to avoid re-declaring labels. <br />
<br />
In my case, items beginning with “Lib5E_” are intended to be called by scripts, while items beginning with “_Lib5E_” are intended to be used as subroutines by the “public” procedures. Of course, there is no reason you couldn’t call them directly.<br />
<br />
You might also note that I’ve included some library information in comment lines (--/|) at the top of the library. These are ignored by ScriptCards, and are a good way to convey requirements, parameters, usage information, etc.<br />
<br />
== Example Libraries ==<br />
<br />
=== dnd5elib ===<br />
<br />
[https://github.com/kjaegers/ScriptCards Download the dnd5elib Library from the ScriptCards GitHub]<br />
<br />
The '''dnd5elib''' library provides a collection of utility procedures that help simplify dealing with the D&D 5E Official Sheet. Some of the procedures in this library require '''chatsetattr''' to be installed in your game. This is a growing library, and currently only has a handful of routines. They are:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Procedure Name !! Notes<br />
|-<br />
| style="white-space:nowrap" | Lib5E_CheckDamageModifiers || This procedure can be used to evaluate vulnerabilities, resistances, and invulnerabilities on an NPC. After setting the --#target| parameters, pass the Lib5E_CheckDamageModifiers procedure a variable name (no reference information) and a damage type (i.e., fire, cold, bludgeoning, etc.) and a string variable with the name passed in as the first parameter will be created that contains text that can be included in a roll line (--=) in order to modify the roll as appropriate. For example, '''-->Lib5E_CheckDamageModifiers|ResistType;fire''' will check the current target character's attributes for "fire" and will either return an empty string (no references), "* 0 [Immune]" if the creature is immune, "\ 2 [Resistant]" if the creature is resistant, or "* 2 [Vulnerable]" if the creature is vulnerable to fire damage.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_DeductSpellSlot || Pass in a character_id and a slot level, and the script will expend one spell slot of that level, capping the value at 0 slots remaining. For Example '''<nowiki>-->Lib5E_DeductSpellSlot|@{selected|character_id};1</nowiki>''' to deduct a first level spell slot from the selected character.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_FindResource || Used to locate a resource value on a character. Pass in a character_id, a resource name, and two variable names. The procedure will check both repeating and non-repeating resources looking for a resource whose name matches what was passed in and return three variables. The first will be a string variable named for the 3rd parameter and contains the attribute name of the resource's "name" field. The second will be a string variable named after parameter 4 and contains the resource's value field attribute name, and the third variable is a Roll Variable, also named after the 4th parameter that contains the current resource value. Example: '''<nowiki>-->Lib5E_FindResource|@{selected|character_id};Crossbow bolts;ResName;ResValue</nowiki>''' will find "Crossbow bolts" as a resource on the character and return [&ResName] which is the name of the resource attribute, [&ResValue] which is the '''name of the attribute that stores the value''' and [$ResValue] which is the current numeric value of the resource.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Global_Attack_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Attack Modifiers (repeating_tohitmod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Bless" for 1d4 active and "Being Cool" for +2 active, I will get a return string " + 1d4 [Bless] + 2 [Being Cool]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Save_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Save Modifiers (repeating_savemod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Bless" for 1d4 active and "Being Cool" for +2 active, I will get a return string " + 1d4 [Bless] + 2 [Being Cool]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Skill_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Skill Modifiers (repeating_skillmod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Guidance" for 1d4 active and "Being Cool" for +2 active, I will get a return string " + 1d4 [Guidance] + 2 [Being Cool]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_AC_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Save Modifiers (repeating_savemod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Shield of Faith" with a value of 2 active, I will get a return string " + 2 [Shield of Faith]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Damage_Modifiers || Pass a character ID and TWO string variable to set the return value. The first string will be for normal damage, and the second will be the additional damage on a crit. This procedure will look through the Global Damage Modifiers (repeating_damagemod_*) for rows that are active (checked on the character sheet) and return two strings with the dice rolls and descriptions for them (for example, if I have "Sneak Attack" with a value of 1d6 normal and 1d6 critical damage active, I will get a return string " + 1d6 [Sneak Attack]" and another string of " + 1d6 [Sneak Attack CRIT]" that can be used in a dice rolls.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_DivineSmiteDice || Used to calculate the number of dice to be rolled for a paladin's Divine Smite. Pass a target token id, a spell slot level, and a string variable to be set to the dice roll amount based on the NPC_TYPE attribute of the target token. The returned variable will contain a dice roll (like "3d8" that can be used in a --= line)<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Character_Summary || Pass a character ID to outputs a mini character sheet, including clickable buttons for attacks, actions, legendary actions, etc. Will automatically detect a PC vs NPC and output the appropriate sections.<br />
|}<br />
<br />
Due to formatting issues with the Wiki, the library code has been moved to a [https://gist.github.com/kjaegers/52f6049ddd257f0a1288aca4bbde13c5 GITHUB GIT]. Please view the GIST in raw mode and copy the text and paste it into a handout called "ScriptCards Library dnd5elib" in your Roll20 Game.<br />
<br />
== What to Know if you are Coming from PowerCards ==<br />
<br />
''Note: This section is a work in progress.''<br />
<br />
While ScriptCards and PowerCard have very similar output goals, their internals and use are quite different. The table below summarizes some of the major differences between the scripts.<br />
<br />
::{| class="wikitable"<br />
|-<br />
! PowerCards !! ScriptCards <br />
|-<br />
| With a handful of exceptions, all lines in a PowerCard macro are intended to produce a line of output on the final card. || With ScriptCards, ONLY the <code>--+</code> and <code>--*</code> statement types produces output <br />
|-<br />
| PowerCards lines begin with two dashes (<code>--</code>) followed by a unique tag name for the line, followed by a vertical bar and the content for the line. || ScriptCards lines begin with two dashes (<code>--</code>) followed by a '''statement type identifier''', which is a single character that identifies the type of line to the interpreter. This is followed by a tag (frequently optional), a vertical bar, and the parameters for the statement being executed.<br />
|-<br />
| PowerCard macros are always processed top to bottom. Lines can be hidden so they don't output anything, but there is no looping or branching (--SkipTo looks like a branch, but it just hides all of the lines until the referenced label. || ScriptCards scripts support true branching, including direct branching (<code>--^</code>) and procedure branching (<code>--></code>) and (<code>--<</code>). Procedures support parameters and a call stack so procedures can be nested to call other procedures.<br />
|-<br />
| All lines in a PowerCards macro need to have unique tags because PowerCards builds the card as a single JavaScript object using the tag names to store what will be displayed. This is why repeated tag names always result in the last one being shown. || ScriptCards tags do not need to be unique, and in the case of many line types are optional.<br />
|-<br />
| PowerCards conditionals result in either showing or hiding the line they are on. || ScriptCards conditionals '''''only''''' support branching as the result of the comparison. This branching can be direct (a GOTO) or procedural (a GOSUB) '''''NOTE: As of version 1.2.0, ScriptCards also supports roll/string variable assignment as a result of conditional evaluation'''''<br />
|-<br />
| PowerCards relies on the Roll20 [[Quantum Roll]] server and inline rolls for all dice functions || ScriptCards includes its own dice roll parser, and '''''does not support''''' inline rolls.<br />
|-<br />
| PowerCards RollIDs (often mistaken for variables) are assigned by analyzing the results of an inline roll, and cannot be referenced in other rolls, so you can't roll a <code>1d4</code> and then roll a <code>1d20</code> and add the <code>1d4</code> result because all of the rolls happen on the chat server before PowerCards gets the macro text. || ScriptCards supports two types of variables: Roll Variables and String Variables. Because ScriptCards uses its own roll parser and is not dependent upon the chat server, rolls and their results can be used in other rolls, math functions, output, etc.<br />
|}<br />
<br />
== Example Scripts ==<br />
<br />
Below are some sample scripts that utilize the various statement types in ScriptCards:<br />
<br />
=== Divine Smite ===<br />
<br />
This script will prompt the user for a spell slot level to expend on a divine smite. It will check the target's npc_type to see if it is an Undead or Fiend, which adds an additional d8 to the smite roll.<br />
<br />
[[File:ScriptCards Divine Smite.png|Divine Smite Script Output]]<br />
<br />
<pre><br />
!scriptcard {{<br />
--#title|Divine Smite<br />
--=DiceCount|?{Spell Slot Level?|1|2|3|4|5|6|7|8|9} + 1<br />
--=IsFiendOrUndead|0<br />
--?"@{target|npc_type}" -inc fiend|>IsBoosted<br />
--?"@{target|npc_type}" -inc undead|>IsBoosted<br />
--=TotalDice|[$DiceCount] + [$IsFiendOrUndead]<br />
--=SmiteRoll|[$TotalDice]d8<br />
--#emoteText|@{selected|token_name} smites @{target|token_name}<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
--+Smite|deals [$SmiteRoll] radiant damage.<br />
--X|<br />
<br />
--:IsBoosted|<br />
--=IsFiendOrUndead|1<br />
--<|<br />
}}<br />
</pre><br />
<br />
==== How It Works ====<br />
<br />
The first line sets the "title" card parameter to "Divine Smite".<br />
<br />
Line 2 Shows a query to the user asking for the spell slot level, adds one and stores the value in the "DiceCount" Roll Variable. The query/dropdown is generated by the chat server prior to the script being executed.<br />
<br />
Line 3 defaults the "IsFiendOrUndead" Roll Variable to 0.<br />
<br />
Lines 4 and 5 compare the target's "npc_type" attribute (passed by the chat server as text) to see if they include either "undead" or "fiend". If true, the IsBoosted subroutine will be called. No parameters are passed to this subroutine.<br />
<br />
Line 6 sets the "TotalDice" variable to the base (DiceCount) number plus the IsFiendOrUndead number, which will be a 0 or a 1.<br />
<br />
Line 7 calculates "SmiteRoll" by rolling a number of d8 equal to the "TotalDice" value.<br />
<br />
Lines 8-10 set the parameters for the emote, which appears above the card content. By setting the sourceToken and the targetToken, their icons will appear in the emote surrounding the text describing the action.<br />
<br />
Line 11 is the only line that actually produces output on the card. It results in "Smite deals # radiant damage".<br />
<br />
Line 12 ends the script execution, preventing the script from continuing and running the subroutines out of context.<br />
<br />
Lines 14-16 are the IsBoosted subroutine, starting with the :IsBoosted label. The IsFiendOrUndead variable is set to 1, and a return from subroutine is executed.<br />
<br />
=== Magic Missile ===<br />
<br />
This script demonstrates using a loop and calling a subroutine to fire a number of missiles determine by the spell slot level used to cast the spell.<br />
<br />
[[File:ScriptCards_MagicMissile_Fixed.png|Magic Missile Script Output]]<br />
<br />
<pre><br />
!scriptcard {{ <br />
--#title|Magic Missile<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
--=MissileCount|?{Spell Slot Level?|1|2|3|4|5|6|7|8|9} + 2<br />
--=DisplayCount|1<br />
--=MissileDamage|0<br />
--#leftsub|Slot level ?{Spell Slot Level?}<br />
--#rightsub|Ranged Attack<br />
--#emoteText|Fred uses a level ?{Spell Slot Level?} spell slot to fire [$MissileCount.Total] missiles of magical force!<br />
--:MissileLoop|<br />
-->FireMissile|<br />
--=DisplayCount|[$DisplayCount] + 1<br />
--?[$DisplayCount] -le [$MissileCount]|MissileLoop<br />
--+Total|Total damage is [$MissileDamage]<br />
--X|<br />
<br />
--:FireMissile|<br />
--=ThisMissile|1d4 + 1<br />
--=MissileDamage|[$MissileDamage] + [$ThisMissile]<br />
--+Missile|[$DisplayCount.Total] Hits for [$ThisMissile] [b]force[/b] damage<br />
--<|<br />
}}<br />
</pre><br />
<br />
==== How It Works ====<br />
<br />
Lines 1-3 set the card title, the source token and the target token. Setting these tokens causes their icons/avatars to appear in the Emote section of the card.<br />
<br />
Line 4 asks the user what spell slot level they wish to use to cast magic missile. The number of missiles fired is equal to 2 plus the spell level, and this is stored in the MissileCount variable.<br />
<br />
Line 5 stores a 1 in the DisplayCount variable. This will be used to control the loop to determine the number of missiles fired and the missile number when displaying damage rolls.<br />
<br />
Line 6 initializes MissileDamage to 0<br />
<br />
Line 7 sets the left subtitle to the text "Slot Level #", where # is the spell slot level being used.<br />
<br />
Line 8 sets the right subtitle to the text "Ranged Attack".<br />
<br />
Line 9 sets the emoteText parameter with a description of the action, including the slot level and number of missiles fired.<br />
<br />
Line 10 is a label for the missile firing loop<br />
<br />
Line 11 Calls the "FireMissile" subroutine<br />
<br />
Line 12 increases the DisplayCount variable by 1<br />
<br />
Line 13 Checks to see if there are still missles to fire (DisplayCount <= MissileCount) and if so branches to MissileLoop<br />
<br />
Line 14 Displays the total damage dealt by the spell.<br />
<br />
Line 15 stops execution of the script to prevent out of context execution of the subroutine.<br />
<br />
Lines 76-21 are the FireMissile subroutine, beginning with the FireMissile label. The 1d4+1 is rolled and assigned to "ThisMissile". The result is added to the existing MissileDamage total, and a line for the current missile is displayed with the missile number and the damage for the missile.<br />
<br />
=== Longsword Attack ===<br />
<br />
This script demonstrates a standard 5E D&D melee weapon attack, including detection of misses, fumbles, hits, and critical hits. If installed, alterbars is used to decrement the target's BAR3 value by the damage dealt.<br />
<br />
[[File:ScriptCards Longsword.png|Longsword Script Output]]<br />
<br />
<pre><br />
!scriptcard {{<br />
--#title|Longsword<br />
--#leftsub|Melee Attack<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
--#emoteText|@{selected|token_name} attacks @{target|token_name}<br />
--=TargetAC|@{target|npc_ac}<br />
--?[$TargetAC.Total] -gt 0|DoneWithAC<br />
--=TargetAC|@{target|ac}<br />
--:DoneWithAC|<br />
--=AttackRoll|1d20 + @{selected|strength_mod} [STR] + @{selected|pb} [PROF]<br />
--+Attack|@{selected|token_name} rolls [$AttackRoll] vs AC [$TargetAC].<br />
--?[$AttackRoll.Base] -eq 20|Crit<br />
--?[$AttackRoll.Base] -eq 1|Fumble<br />
--?[$AttackRoll.Total] -ge [$TargetAC.Total]|Hit<br />
--+Miss|The attack missed.<br />
--^Final|<br />
<br />
--:Fumble|<br />
--+Fumble!|The attack went horribly wrong.<br />
--^Final|<br />
<br />
--:Hit|<br />
--=Damage|1d8 + @{selected|strength_mod} [STR]<br />
--+Hit!|The attack hit @{target|token_name} for [$Damage] slashing damage.<br />
--@alter|_target|@{target|token_id} _bar|3 _amount|-[$Damage]<br />
--^Final|<br />
<br />
--:Crit|<br />
--=Damage|1d8 + @{selected|strength_mod} [STR] + 1d8 [CRIT]<br />
--+Critical Hit!|The attack hit @{target|token_name} for [$Damage] slashing damage.<br />
--@alter|_target|@{target|token_id} _bar|3 _amount|-[$Damage]<br />
<br />
--:Final|<br />
}}<br />
</pre><br />
<br />
==== How it Works ====<br />
<br />
In lines 1-5, we set the title, subtitle, and emote text along with the tokens for the emote area.<br />
<br />
Lines 6-9 allow us to determine the AC of the target. On the 5E Roll20 sheet, NPCs armor class is stored in "npc_ac", while PCs armor class is in "ac". First we grab npc_ac and if it is zero, we check AC.<br />
<br />
Line 10 rolls the attack roll, rolling 1d20 and adding the attacker's strength modifier and proficiency bonus<br />
<br />
Line 11 displays the result of the attack roll on the card<br />
<br />
Lines 12-14 determine what kind of result the attack had. If the .Base value of the roll was 20, we branch to "Crit". If it was 1, we branch to "Fumble". If the .Total value of the roll was greater than or equal to the AC that was determined in Lines 6-9, we branch to Hit.<br />
<br />
Assuming we didn't branc anywhere, the result of the attack was a miss, so we display that on line 15 and then branch to "Final"<br />
<br />
This is followed by three branch segments, :Fumble, :Hit, and :Crit. A fumble displays a text message and branches to :Final.<br />
<br />
On a hit or a crit, we roll Damage (adding additional damage dice on a crit). We display a "Hit!" or "Critical Hit!" message and then make an API call to AlterBars, passing it the token id, bar we want to modify (3 in this case), and the amount we want to modify by the Damage value.<br />
<br />
=== Party Health Status ===<br />
<br />
This example calculates the current Hit Points remaining and HP percentage for each character and creates a color-coded display with the current party status.<br />
<br />
[[File:ScriptCards Party Health.png]]<br />
<br />
<pre><br />
!scriptcard {{<br />
--#title|Party Status<br />
--#titleCardBackground|#33CC33<br />
--#oddrowbackground|#bfee90<br />
--#evenrowbackground|#90eebf<br />
-->HealthCheck|@{Quej Grastra|character_id}<br />
-->HealthCheck|@{Brim Cheuto|character_id}<br />
-->HealthCheck|@{Odug Ututees|character_id}<br />
--X|End of card Execution<br />
<br />
--:HealthCheck|<br />
--=HealthPerc|[*[%1%]:hp] / [*[%1%]:hp^] * 100 \ 1<br />
--=HealthColor|000000<br />
--?[$HealthPerc.Total] -gt 50|HealthSkip<br />
--=HealthColor|FF0000<br />
--:HealthSkip|<br />
--+[*[%1%]:character_name]|has [#[$HealthColor.RollText]][*[%1%]:hp] of [*[%1%]:hp^][/#] HP [R]([$HealthPerc.Total]%)[/R]<br />
--<|End of HealthCheck<br />
}}<br />
</pre><br />
<br />
==== How it Works ====<br />
<br />
Lines 1-4, we set the card title, and set the title background and row background colors to shades of green.<br />
<br />
Lines 5-7 make gosub calls the the "HealthCheck" subroutine, passing in the character ID of each of the named characters (these are the names of the characters in my test game)<br />
<br />
Line 8 terminates the script execution.<br />
<br />
The remaining lines of the script are the HealthCheck subroutine, which works like this:<br />
<br />
Line 10 is the subroutine label (:HealthCheck)<br />
<br />
Line 11 uses the character id passed as a parameter and combines it with character attribute lookup *(...) to retrieve the value of "hp" and "hp<nowiki>^</nowiki>" for the character. The <nowiki>^</nowiki> character is used to specify that we want the MAX value for this attribute for the second call. We divide these two numbers and multiple by 100 to get a percentage. Finally, we use integer division by 1 to round the percentage and drop the decimals. The end result gets stored in the HealthPerc roll variable.<br />
<br />
Line 12 defaults to color of the health text to black<br />
<br />
Line 13 check to see if the health percentage is greater than 50. If so, it branches to HealthSkip, preventing the script from executing line 13.<br />
<br />
Line 14 sets the color of the health text to red<br />
<br />
Line 15 is the label that will be branched to from Line 13 to skip the red coloring<br />
<br />
Line 16 again uses character attribute substitution and the passed parameter value to output a display line containing the character name, the colorized health total, and the percentage value. The percentage is right-justified.<br />
<br />
Line 17 returns from the HealthCheck subroutine.<br />
<br />
=== Expanded Magic Missile Script ===<br />
<br />
This is the expanded and enhanced version of the Magic Missile script covered in {{yt|watch?v=u50xvNzS9Zk | this video}}. It includes visual and audio effects, checking and deducting spell slots, and applying damage using either Token-Mod or Alterbars.<br />
<br />
<pre><br />
!scriptcard {{ <br />
--#title|Magic Missile<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
<br />
-->GetAndCheckSlotInformation|<br />
<br />
--=MissileCount|[$SlotLevel] + 2<br />
--=DisplayCount|1<br />
--=MissileDamage|0<br />
--#leftsub|Slot level [$SlotLevel]<br />
--#rightsub|Ranged Attack<br />
--#emoteText|@{selected|character_name} uses a level [$SlotLevel.Total] spell slot to fire [$MissileCount.Total] missiles of magical force!<br />
<br />
--:MissileLoop|<br />
-->FireMissile|<br />
--=DisplayCount|[$DisplayCount] + 1<br />
--?[$DisplayCount] -le [$MissileCount]|MissileLoop<br />
--+Total|Total damage is [$MissileDamage]<br />
-->DeductSpellSlot|<br />
--#rightsub|Level [$SlotLevel] Left: [$SlotsRemaining] <br />
-->PlayEffects|none;burst-smoke;beam-magic;spell_01<br />
-->ApplyDamageTokenmod|@{target|token_id};3;-[$MissileDamage]<br />
-->ApplyDamageAlterbars|@{target|token_id};3;-[$MissileDamage]<br />
--X|<br />
<br />
--:FireMissile|<br />
--=ThisMissile|1d4 + 1<br />
--=MissileDamage|[$MissileDamage] + [$ThisMissile]<br />
--+Missile|[$DisplayCount.Total] Hits for [$ThisMissile] [b]force[/b] damage<br />
--<|<br />
<br />
--:GetAndCheckSlotInformation|<br />
--=SlotLevel|?{Spell Slot Level?|1|2|3|4|5|6|7|8|9}<br />
--=SlotsTotal|[*S:lvl[$SlotLevel]_slots_total]<br />
--=SlotsExpended|[*S:lvl[$SlotLevel]_slots_expended]<br />
--?[$SlotsExpended.Total] -ge [$SlotsTotal.Total]|NoSlotsLeft<br />
--<|<br />
<br />
--:NoSlotsLeft|<br />
--+|[*S:character_name] has no level [$SlotLevel.Total] spell slots available.<br />
--X|<br />
<br />
--:DeductSpellSlot|<br />
--=SlotsExpended|[$SlotsExpended] + 1<br />
--@setattr|_charid [*S:character_id] _lvl[$SlotLevel]_slots_expended|[$SlotsExpended] _silent<br />
--=SlotsRemaining|[$SlotsTotal] - [$SlotsExpended]<br />
--<|<br />
<br />
--:PlayEffects|Parameters are : source effect; target effect; line effect; sound effect<br />
--vtoken|@{selected|token_id} [%1%]<br />
--vtoken|@{target|token_id} [%2%]<br />
--vbetweentokens|@{selected|token_id} @{target|token_id} [%3%]<br />
--@roll20AM|_audio,play,nomenu|[%4%]<br />
--<|<br />
<br />
--:ApplyDamageTokenmod|Parameters are tokenid;bar#;amount<br />
--@token-mod|_ignore-selected _ids [%1%] _set bar[%2%]_value|[%3%]<br />
--<|<br />
<br />
--:ApplyDamageAlterbars|<br />
--@alter|_target|[%1%] _bar|[%2%] _amount|[%3%]<br />
--<|<br />
}}<br />
</pre><br />
<br />
[[Category:Featured articles]]</div>5004103https://wiki.roll20.net/D%26D_5E_by_Roll20D&D 5E by Roll202021-10-01T12:10:26Z<p>5004103: /* Directly Referencing Attributes */</p>
<hr />
<div>{{revdate}}{{HCbox|{{hc|360037773573-5th-Edition-OGL-by-Roll20 D&D 5E by Roll20}} }}<br />
[[File:5E OGL Sheet Core v2.6.png|500px|thumb|right|The '''D&D 5E by Roll20''' Character Sheet]]<br />
<br />
This is the community-driven documentation for the '''[[5E|D&D 5E]] by Roll20''' character sheet. Previously the sheet was known as the '''"5th Edition OGL Sheet"''' or just the '''"OGL Sheet"'''.<br />
<br />
=The Basics=<br />
This page is a ''[[Community Wiki]]'' guide to the Official D&D 5th Edition character sheet, which is updated with info tricks that might not be covered by the {{hc|articles/360037773573-5th-Edition-OGL-by-Roll20 official sheet documentation}}.<br />
<br />
<br />
To find out about the latest updates, issues and talk about the sheet, check the {{fpl|10096810/ D&D 5th Edition by Roll20 (Q2Y2021)}}-thread on the {{forum|category/277980 forums}}.<br />
<br />
<br />
[[Bug|Bug reports]] for the sheet is best reported in the same thread. If you find bugs in the 5E Compendium or 5E marketplace content, {{bug}}.<br />
<br />
<br />
__TOC__<br />
<br />
==Adding the Character Sheet to a Game==<br />
[[File:D&D5E-Roll20-sheet-selection.png|300px|thumb|right|The Sheet Selection Menu]]An official or community contributed character sheet [[Add_character_sheet#Adding_a_Character_Sheet_to_your_Campaign|can be added to any game when you first create it]]. On the Game Creation screen, underneath the large blue '''“I’m Ready, Create Game!”''' button, is the '''“Optional: Choose a Character Sheet”''' section. Located here is a drop down menu that lists all the character sheets built either by Roll20 officially or created by the community. These sheets are sorted under their respective RPG Systems in alphanumerical order. Once selected, a preview of the character sheet will load upon the creation page for you to review as well as showcase relevant information about the sheet, such as the sheet’s creator and its key features.<br />
<br />
<br />
The '''D&D 5E by Roll20''' Sheet can be found under either: '''Sheets by Roll20''' → D&D 5E by Roll20 OR '''Dungeons and Dragons 5E''' → D&D 5E by Roll20<br />
<br />
<br />
If you want to add a character sheet to an existing campaign, you can find this drop down menu once again by accessing the [[Game Settings Page]] from the [[Game_Management#Game_Details_Page|Game Details]]-page.<br />
<br />
{{mbox | text = '''NOTE:''' If you have added custom attributes to your character journals prior to adding a character sheet to a campaign, you may want to delete them first. Adding a character sheet to a campaign will create its own set of custom attributes on all of your character journals, but it will reuse any attributes encountered if they share the same name. This can cause calculation issues on the sheet.}}<br />
<br />
<br />
If you were previously using either the [[DnD5e Shaped Character Sheet|D&D 5E (Shaped)]] or [[DnD5E_Community_Contributed|D&D 5E (Community Contributed)]] sheets and wish to transfer over to the '''D&D 5E by Roll20''' version, it's a good idea to ask help on the [https://app.roll20.net/forum/category/277980 forums].<br />
<br />
<div style="clear: both"></div><br />
<br />
==Where to Find the Sheet==<br />
Once a character sheet has been added to a game, and once inside it, on all [[Journal#Characters|Characters Journals]], a new tab will be available between the '''“Bio & Info”''' and '''“Attributes & Abilities”''' tab labelled '''“Character Sheet”'''. Much like the Attributes & Abilities tab, only players who have been granted Edit permissions for the journal entry will be able to access the Character Sheet tab.<br />
<br />
''See also:'' '''[[Add_character_sheet#Adding_New_Characters_In-Game|Create new character sheets to your players]]'''<br />
<br />
==Sheet Features==<br />
The '''D&D 5E by Roll20''' sheet has all of the functionality of a pen and paper character sheet, and much more. Certain aspects of the sheet have been streamlined or automated to remove bookkeeping and speed up gameplay. The key features are auto-calculations, [[Macro|macro]] buttons, and [[D&D 5e by Roll20 Roll Templates|roll templates]]. The sheet defaults to using the rules as printed in the D&D 5E SRD, however it's dynamic enough to allow you and your group to use many custom house rules you might want.<br />
<br />
===Auto Calculations===<br />
Many parts of the sheet use auto calculations to fill in derived attributes with the expectation that you're using the rules as printed in the 5th Edition SRD. Many of these calculated traits can be modified from the character sheet's <span style="font-family:Pictos;">y</span> [[D&D 5E by Roll20#Settings Page|Settings]]-tab, and those set by Sheet Workers can be edited directly. Below are some examples of Sheet Worker and Auto Calculation functionality:<br />
<br />
* '''Class''' - Changing the character's class from the header will automatically update the character's saving throw proficiencies, their hit die type, spell casting ability, and spell save DC. <br />
* '''Level''' - Changing the character's level will also update their proficiency bonus, number of spells per day, and more.<br />
* '''Attributes''' - Changing one of the character's attributes will also update the related modifier, skills that are based on that attribute, and derived stats such as initiative or passive perception.<br />
<br />
===Roll Buttons and Roll Templates===<br />
[[File:5E_OGL_Sheet_Rollable_Buttons.gif|right|frame|Any label that highlights in red when the mouse hovers over it is rollable.]]<br />
''Main Page:'' '''[[D&D 5e by Roll20 Roll Templates|D&D 5E by Roll20 Roll templates]]'''<br />
<br />
Most of the stats in the game can be rolled by hovering over their name, the stat will turn red, and then left-clicking the mouse. This is true for Attributes, Saves, Skills, Hit Dice, Death Saves, Tool Proficiencies, Attacks & Spellcasting, Spell Cards, and NPC Actions/Attacks. Any of these roll buttons can be dragged directly from the sheet to your [[Macro Quick Bar]], enabled from the <span style="font-family:Pictos;">y</span> [[My Settings]]-tab of Roll20's [[Sidebar]].<br />
<br />
Player characters have both a simple and attack [[D&D 5e by Roll20 Roll Templates|roll template]] that is output to the {{Text Chat}}-tab on the right hand [[Sidebar]]. The simple template is used for everything except for attacks. The attack template is shaped to show up in three pieces; the attack at the top, information in the middle, and damage at the bottom. Depending on your sheet settings, the damage will not roll automatically unless you click on the name of the attack from the roll template in the chat tab. This was designed to simulate the tabletop experience of rolling to attack and then rolling damage if necessary. You can change this behavior in the sheet <span style="font-family:Pictos;">y</span> [[D&D 5E by Roll20#Settings Page|Settings]]-tab, tab under "Auto Damage Roll".<br />
<br />
<div style="clear: both"></div><br />
<br />
====Rolling for Advantage and Disadvantage====<br />
With the '''D&D 5E by Roll20''' Sheet, the [[D&D 5E by Roll20#Settings Page|default sheet settings]] has Advantage set to ''always'' rolled for convenience purposes. It is commonly agreed upon that a gaming group uses the left roll result when advantage is not being used for a check. When advantage or disadvantage is in play, simply choose the higher or lower result among the two per usual. You can change this behavior in the sheet <span style="font-family:Pictos;">y</span> [[D&D 5E by Roll20#Settings Page|Settings]]-tab (gear icon at the top right of the page), tab under "Roll Queries". You have the choice of "Always Roll Advantage" (the default setting), "Advantage Toggle", "Query Advantage", or "Never Roll Advantage".<br />
<br />
'''Advantage Toggle:''' The Advantage Toggle will add three buttons to the top of your character sheet: "Advantage", "Normal", and "Disadvantage". You can click on any of these to roll for Advantage (the highest roll result will highlight in black), Disadvantage (the lowest roll result will highlight in black), or a single d20.<br />
<br />
'''Query Advantage:''' The Query Advantage setting will prompt a dialog box to appear whenever you roll from your sheet. It will ask you to select what sort of roll want to do (Normal, Advantage, Disadvantage). After choosing the type you want, the roll will occur in chat.<br />
<br />
'''Never Roll Advantage:''' When rolling from your sheet, only a single d20 will be rolled.<br />
<br />
===Resizable Text Fields===<br />
[[File:5E_OGL_Sheet_Resizable_Text_Fields.gif|right|frame|Making a text field larger is just a matter of click and dragging.]]There are many free-text fields on the sheet that give you a place to keep information that doesn't necessarily follow a specific format. All of the fields on the Bio Tab are free-text fields as well as the Description fields present for attacks, spells, equipment, features & traits, and NPC actions. If your text overflows past the bottom of a text field, you can resize it to view the content in its entirety by clicking and dragging the bottom right corner icon shown in the adjoining image.<br />
<br />
<br />
At present, these fields can only contain raw text. There are no formatting options (bold, italic, etc.) available.<br />
<br />
<div style="clear: both"></div><br />
<br />
===The Padlock Button and Organizing Elements===<br />
(aka. '''[[Character_Sheets#Repeating_Section|Repeating Section]]''')<br />
[[File:5E_OGL_Sheet_Padlock.gif|right|frame|The Padlock Toggle]]There is a <span style="font-family:Pictos;">(</span> (padlock) icon set at the bottom of several different fields of the '''D&D 5E by Roll20''' Sheet. It is used where a player is meant to add entries such as individual attacks, actions, pieces of equipment, features & traits, tool proficiences & custom skills, other proficiencies & languages, and spells. This icon behaves as a toggle button. <br />
<br />
When set in the <span style="font-family:Pictos;">(</span> locked position (default), a player can add new entries into the field. When the button is toggled to <span style="font-family:Pictos;">)</span>(unlocked), a player can no longer add new entries, but they will be able to reorder or delete any of the existing ones. The <span style="font-family:Pictos;">#</span>(red trash bin)-icon overlaid on the right hand side of the entry will delete it.<br />
<br />
{{Ambox<br />
|nocat=true<br />
| type = content<br />
| text = '''Deleting an entry cannot be undone!''' On left side of every entry while the padlock is <span style="font-family:Pictos;">)</span> unlocked is a re-sort icon symbolized by '''<big>≡</big>'''(three parallel lines). By clicking and dragging on this icon, you can rearrange the order of the entries in the field.<br />
}}<br />
<br />
{{Ambox<br />
|nocat=true<br />
| type = content<br />
| text = Some of the features of '''Repeating Sections''' do not work when the [[Character_Sheets#Character_Sheet_in_a_separate_window|Character Sheet is in a separate window]].<br />
}}<br />
<br />
<br />
<div style="clear: both"></div><br />
<br />
==Utilizing the 5th Edition SRD Compendium==<br />
[[File:5E_OGL_Sheet_Compendium.png|right|The Compendium Tab]]Upon adding the D&D 5E by Roll20 Character Sheet to a campaign, the [https://app.roll20.net/compendium/dnd5e/BookIndex| 5th Edition SRD Compendium] is automatically enabled for use from it's own <span style="font-family:Pictos;">i</span> [[Compendium]]-tab in the '''[[Sidebar]]''' of the application. It's located between the {{Journal}} and <span style="font-family:Pictos Custom;">u</span> [[Jukebox]]-tabs, and is accessible for both GM and Player alike.<br />
<br />
<br />
The <span style="font-family:Pictos;">i</span> [[Compendium]] allows for rapid searching of all rules, classes, monsters, spells, items, and more that are included in the 5th Edition SRD. This minimizes time spent for the gaming group to leaf through a book in the middle of a session for a rule clarification. Even better, both the GM and the Player can utilize dragging and dropping* from the <span style="font-family:Pictos;">i</span> [[Compendium]]-tab directly to your character sheets. This makes statting NPCs and PCs far faster than inputing everything manually.<br />
<br />
{{mbox | text = '''NOTE:''' The 5th Edition SRD is similar but NOT identical to the ''Dungeons and Dragons'' 5th Edition Rule Book. Some skills, classes, creatures, items, and other elements found within the ''Dungeons and Dragons'' rule book are strictly intellectual property of Wizards of the Coast and not accessible through their Open-Game License(OGL).}}<br />
<br />
<br />
===Statting PCs===<br />
Dragging from the <span style="font-family:Pictos;">i</span> [[Compendium]] works for the Equipment and Spell fields of the PC Sheet. This will not only carry over the name of the item or spell, but the relevant attack and damage rolls and any rules or flavor text that comes with it. Adding Compendium items in this fashion also automatically adds the equipment item (if it's a weapon) or spell to the Attacks & Spellcasting field to roll directly from. Items that modify a character's Attributes, Saves, AC, To Hit, Damage, Spell Attacks, and Spell DC will be automatically calculated on the sheet when dragged in. For example, if a Belt of Giant Strength is dragged to a sheet, the strength Attribute Score will become highlighted in blue and its attribute score will be increased. An asterisk is appended to the right of the score to also signify that it has been modified by an item. When you mouse over this number, the strength Attribute Score will revert back to what its unmodified total so you can refer back to it. Dropping a Compendium items that is an ammunition type (arrows, crossbow bolts, blowgun darts, etc) will automatically fill out a resource field for that item and link it to its entry in the Equipment section.<br />
<br />
To insert a Compendium item into the character sheet, run a search for the Item or Spell you want to add in the <span style="font-family:Pictos;">i</span> [[Compendium]]-tab. Once found, click and drag on the Compendium item's name so that it creates a little named tile that follows along with your mouse. Drag this over to the character sheet, it doesn't matter where. A text box that reads, "ACCEPTING DROP FROM COMPENDIUM" will appear on your sheet if this is done correctly. Let go of the tile and the entry will be auto-completed with all the data pertaining to the the Compendium entry in the correct location on the sheet. You can see this in action below under [[#Equipment|Equipment]].<br />
<br />
===Statting NPCs===<br />
You can fill out an entire NPC sheet in a single drag and drop. Run a search for the NPC you want to create from the <span style="font-family:Pictos;">i</span> [[Compendium]]-tab. Once found, click and drag on the NPC name so that it creates a little named tile that follows along with your mouse. Drag this to anywhere over the Tabletop area of the screen. Let go of the tile and a new character journal will be created named after the NPC from the Compendium entry. Its sheet will be changed over to the NPC sheet and filled with the entire NPC entry from the Compendium including their Actions, Reactions, and Legendary Actions if applicable. If you're using one of the Compendium expansions bought from the Roll20 Marketplace like the Monster Manual or Volo's Guide to Monsters, token art will also be pulled from the Compendium entry, placed on the table, and linked to your NPC's journal.<br />
<br />
You can also drag an NPC entry from the Compendium to an existing journal entry if you have the sheet open. If the sheet is in PC sheet mode, it will automatically change it over to the NPC sheet, and add its entry elements to it.<br />
<br />
One thing to note about dragging a stat block over from the Compendium is that it uses an ''additive'' behavior. It will not replace anything that you have already entered manually.<br />
<br />
=The PC Sheet=<br />
The '''D&D 5E by Roll20 Sheet''' contains both the PC Sheet ''and'' the NPC Sheet. By default, a new character journal is set to the PC sheet, but you can switch between the two by toggling it from the [[#Settings Page|General Options Settings]]. The PC Sheet is split up into four pages and can be selected from the buttons just underneath the header at the top of the sheet. They are listed from left to right order: The [[#Core Page|Core Page]], The [[#Bio Page|Bio Page]], The [[#Spells Page|Spells Page]], and The [[#Setting Page|Setting Page]].<br />
<br />
== Creating and Leveling up a character with Charactermancer ==<br />
Players and GMs using the '''D&D 5E by Roll20''' Sheet can use the Charactermancer to create and level up characters.<br />
<br />
'''How to use the Charactermancer for [[Charactermancer (D&D Fifth Edition)|character creation and leveling]].'''<br />
<br />
<br />
{{Ambox<br />
|nocat=true<br />
| type = content<br />
| text = The Charactermancer do not work when the [[Character_Sheets#Character_Sheet_in_a_separate_window|Character Sheet is in a separate window]].<br />
}}<br />
<br />
==Core Page==<br />
[[File:5E_OGL_PC_Core_Guide.jpg|right|frame|The Core Page]]The Core Page is selected by default and has most of the information you'll want to use on a regular basis to play your character. This should look very similar to the content you would normally find on the first sheet of the physical "D&D 5E by Roll20" player character sheet. The screenshot at the top of this wiki page displays the entirety of the Core Page. <br />
===(1) Core Header===<br />
[[File:D&D5E-Roll20-core-header.png|550px]]<br />
<br />
The header block at the top of the sheet changes based on the page you have selected. On the Core page you can select a class by its dropdown menu. The available options from the dropdown are: Barbarian, Bard, Cleric, Druid, Fighter, Monk, Paladin, Ranger, Rogue, Sorcerer, Warlock, and Wizard. You can create a custom class from the Settings Page.<br />
<br />
Once a class has been selected you can update the class's level by changing the number next to the class. The sheet will also automatically mark the abilities that class has proficiency in as well as automatically select the dice that will be used when Hit Dice are rolled. You can change the Hit Dice setting manually from the options menu. If your character multi-classes, then the secondary class and its level will appear beside the primary class. This Class and Level field can hold up to four classes if desired.<br />
<br />
The fields for Background, Race, Alignment, and Experience Points allow you to fill in whatever text you wish to put in them. The Character Name persists over all pages of the sheet and is tied to the name you give to the journal entry. Changing it on the sheet itself will also change the name on the character journal and vice versa once it is closed.<br />
<br />
===(2) Attributes===<br />
<br />
[[File:5E_OGL_Sheet_Attribute_Block.jpg|left]]Along the left side of the sheet are listed the 6 primary attributes: Strength, Dexterity, Constitution, Intelligence, Wisdom, and Charisma. These attributes are used by almost every other calculation on the sheet, as they are the core definition of a character. Each attribute block has the core attribute score, which can be changed by modifying the number in the oval at the bottom of each block, and, inside the square, the attribute modifier which is auto-calculated based on the score below it. All racial ability score increases must be manually added to the core attribute score using the settings "gear" symbol at the top of the page (where the Core, Bio, and Spells buttons are located.) The attribute modifier uses the following calculation to set the value:<br />
<br />
<br />
<code>[[floor((@{strength}-10)/2)]]</code><br />
<br />
The attribute can be referenced by its name, such as @{dexterity} while the attributes modifier can be referenced by adding the mod suffix, @{dexterity_mod}.<br />
<br />
<div style="clear: both"></div><br />
<br />
===(3) Inspiration===<br />
<br />
[[File:D&D5E-Roll20-inspiration.png|left]]You can track whether or not you have Inspiration by clicking the circle next to the Inspiration block at the top left of the Core page. This will toggle a dragon spiral icon on and off for indication purposes.<br />
<br />
<div style="clear: both"></div><br />
<br />
===(4) Proficiency Bonus===<br />
<br />
[[File:5E_OGL_Sheet_Proficiency.png|left]]Your character's proficiency bonus is listed near the top left of the page. You cannot modify this value manually, instead it is automatically set based off your character's over-all level. Your character's Level can be set by changing the number next to your Class name in the [[#header_info|Header]] at the top when on the Core page.<br />
<br />
<div style="clear: both"></div><br />
<br />
===(5) Saving Throws===<br />
<br />
[[File:5E_OGL_Sheet_Saving_Throws.png|left]]Next to the core Attributes on the left side of the page is a list of the same attributes to be used in making saving throws. To mark an attribute that your character has proficiency in for saving throws, check the box next to the appropriate attributes. When you select a class in the header section of the Core page it will automatically check the correct boxes for that class's proficiencies.<br />
<br />
You can add an additional field to Saving Throws to serve as a Global Save Modifier. An example is if the character is under the influence of the Bless spell and can roll a 1d4 in addition to the result of their saving throws. This is enabled from the Settings Page under General Options. Once enabled a seventh checkbox and field will be added at the bottom of the Saving Throws block with a text field to enter the additional die roll. For this example, you could enter "1d4[BLESS]" in the global checkbox's text field that you can enable when the character is under the effects of the Bless spell. The word between the brackets becomes a label that can be seen when you mouse over the roll result in chat. While this Global Save Modifier is checked, every roll made from the Saving Throws block and performing a Death Save will add this modifier to the result.<br />
<br />
<div style="clear: both"></div><br />
<br />
===(6) Skills===<br />
[[File:5E_OGL_Sheet_Skills.png|left]]<br />
To the right of the Core Attributes is a list of all of the character's Skills. Each skill can be rolled by clicking on the skill name. If you have proficiency in a specific skill, then you would check the box next to the skill name, this will automatically add your proficiency bonus to that skill's checks. Each skill also lists the core attribute, that is used in the roll calculations, next to it in parenthesis.<br />
<br />
You can set advanced skill options for the Settings page, such as skill expertise, flat bonuses from class archetypes or feats, as well as Jack of All Trades.<br />
<br />
<div style="clear: both"></div><br />
<br />
===(7) Armor Class, Initiative, & Speed===<br />
<br />
[[File:D&D5E-Roll20-AC-Init-Speed.png|left]]The Armor Class & Speed blocks at the top center of the page can be used to keep track of your Armor and Speed values. The Initiative block cannot be modified manually, but instead is auto-calculated based off your character's Dexterity. If you have any additional initiative modifiers you can add them on the {{gear}} [[#Settings Page|Settings Page]] under Initiative Modifier in the Class Options block.<br />
<br />
Armor Class can also be tracked automatically by using the [https://app.roll20.net/compendium/dnd5e/BookIndex Compendium] compatible inventory, on by default.<br />
<br />
You can configure a custom AC calculation using the {{gear}} [[#Settings Page|Settings Page]] under the Attribute Tracking section. It's listed as "Armor Class Tracking" and is set to "Automatic" by default. If you select Custom, you can select up to two different attributes to apply to the character's armor class.<br />
<div style="clear: both"></div><br />
<br />
====Using the Global AC Modifiers====<br />
If you check the "Show Global AC Modifier" field in the character sheet General Options settings, the sheet will display a repeating section to configure and apply different modifiers to AC. So, for example, if your character has a common bonus, such as from a spell or a conditional feat or fighting style, you can toggle that AC bonus from the character sheet directly.<br />
<br />
====Rolling for Initiative and the Turn Order Tracker====<br />
Clicking on the word INITIATIVE will roll that character's initiative score. If your players have [[Token|tokens]] linked to their character sheets, they can roll their initiative ''and'' simultaneously add their character and its initiative score to the {{Turn Tracker}} automatically. What is required of the player is that their linked token must be currently selected on the Tabletop before they roll off their sheet.<br />
<br />
If you would like to enable a tie breaker component to Initiative, there is an option to enable this from the [[#Settings Page|Settings Page]] under the "Attribute Options" block. What this does is that it will add your dexterity Attribute Score as a decimal value to your Initiative. So if you have a character with a dexterity attribute score of 14, your initiative modifier will change from a <code>2</code> to a <code>2.14</code>.<br />
<br />
===(8) Hit Points & Temporary Hit Points===<br />
[[File:5E_OGL_Sheet_HP.png|left]]The Current Hit Points and Temporary Hit Points blocks are used to keep track of your character's Hit Points (HP). Inside the Current Hit Points block, at the top, is a line that lists the character's maximum amount of HP. <br />
<br />
<br />
When your character takes damage, if they have any, it should be subtracted from their Temporary Hit Points first, then any remaining damage would then come off of the character's Current Hit Points.<br />
<br />
<div style="clear: both"></div><br />
<br />
===(9) Hit Dice===<br />
[[File:5E_OGL_Sheet_Hit_Dice2.png|left]] The Hit Dice block is used to keep track of and roll your character's hit dice. Inside the Hit Dice block, at the top, is a line to keep track of the total number of dice your character can have. In the main area of the block you would keep track of the remaining hit dice. Clicking the "HIT DICE" label will roll the hit dice for your selected class automatically. If you wish to change the dice that is rolled you can do so in the Class Options section of the [[#Settings Page|Settings Page]] ({{gear}} icon). <br />
<br />
<br />
If your character is multi-classed, when rolling your hit dice (by clicking "''HIT DICE''", a pop-up will ask which of your character's current class's hit dice you want to roll. This input accepts only numerals a input to make automatic tracking of the [[API:A Guide to the API|API]] possible.<br />
<div style="clear: both"></div><br />
<br />
===(10) Death Saves===<br />
[[File:5E_OGL_Sheet_Death_Saves.png|left]]The Death Saves block is used to keep track of your character's death save rolls once they have been knocked out. You can click the "DEATH SAVES" label to make a death save roll. If you roll greater than 10 you would check one of the boxes next to "Successes" otherwise you would check a box next to "Failures". If your character has any modifiers to their death save rolls they can be added in the Class Options section of the Settings Page(gear icon).<br />
<div style="clear: both"></div><br />
<br />
===(11) Attacks & Spellcasting===<br />
[[File:5E_OGL_Sheet_Attacks_And_Spellcasting.png|left]]The Attacks & Spellcasting block in the center of the Core page of this character sheet will be one of the most often used sections. To start, you can manually add any attack or spell to this section by hovering over the block and clicking the "Add" button(the <span style="font-family:Pictos;">&</span> symbol). This will open a form that can be filled out with all of the information about the specific attack or spell you are adding. <br />
<br />
<br />
This section will automatically add attacks, with all the stats, for spells that have an attack component when they are added to your spell sheet on the [[#Spells Page|Spells Page]]. This happen both if you add the spell manually or if you drag and drop a spell from the <span style="font-family:Pictos;">i</span> [[Compendium]]. An attack is also automatically created if you drag and drop an item from the Compendium into your sheet.<br />
<br />
<div style="clear: both"></div><br />
[[File:Poisoned Dagger 5e Attack.png|right|frame|An example of an attack form filled out for a physical attack using a +1 Poisoned Dagger]]For example, lets say Erin the Bold has a +1 Poisoned Dagger that has the stats of a regular dagger, but also metes out an additional 1d6 of poison damage alongside the typical 1d4 points of piercing damage. The image displayed to the right is how the attack would be set up:<br />
<br />
<br />
Since this is a [https://app.roll20.net/compendium/dnd5e/Items:Dagger#h-Dagger dagger], and daggers have the "[https://app.roll20.net/compendium/dnd5e/Weapons#h-Weapons Finesse]" attribute I can chose either STR or DEX for my bonus attribute. Erin is quicker than she is strong, so we will pick DEX as the attribute to attack with, as well as checking the "proficient" checkbox since Erin is experienced with using these sorts of weapons. She doesn't have any other gear that might make her attacks better, so we will leave the generic bonus between the attribute and proficiency blank, or 0. Being a +1 Poisoned Dagger means that it is also magical, so it gets a 1 in the magic bonus slot just below. A dagger can also be used as a thrown weapon, so we've added the weapon's throwing range info to the "Range" field. Since a weapon does damage, we have checked the first "Damage" checkbox and filled in the required fields. This dagger does 1d4 piercing damage + Erin's DEX mod + 0 bonus damage (this would be used for bonus damage on top of the magical +1) and it doesn't have anything to change the critical damage so we just put the same damage into the "crit" box. Because this dagger can also cause poison damage, we also check the second "Damage" checkbox and fill in the info for the 2nd set of damage. The poison does a flat 1d6 poison with no extra bonuses, so we've selected "-" to say there is no attribute that adds to this damage. This damage also doesn't have anything to make the crit different so we set that to 1d6 as well. There are no extra saving throws or effects that are included with this attack, so we leave these additional sections blank. <br />
<br />
These additional effect sections will be used more commonly with spells, like [https://app.roll20.net/compendium/dnd5e/Fireball#h-Fireball Fireball], where you would require a DEX save against your SPELL DC, which will be set according to your character's spell casting level. For a fireball, the save effect would be "half damage" and the "Description" would be something like "Hits all creatures within 20 ft of the explosion point".<br />
<br />
After you are done modifying all of individual stats for an attack you can click the gear icon at the top right of that section and it will hide the stats for that attack. If ever you need to change these stats in the future you can hover over the entry and click the <span style="font-family:Pictos;">y</span>(gear)-icon that shows up to unhide the stats section. <br />
<br />
<div style="clear: both"></div><br />
====Adding Global Attack and Damage Modifier====<br />
You can add two special entries to the Attacks & Spellcasting block to handle to global Attacks and Damage modifications to rolls. An example is if the character is under the influence of the Bless spell and can roll a 1d4 in addition to the result of their attack roll. This is enabled from the [[#Settings Page|Settings Page]] under General Options. Once enabled, a checkbox will be added at the bottom of the Attacks & Spellcasting block with a text field to enter the additional die roll. For this example, you could enter <nowiki>"1d4[BLESS]"</nowiki> in the global checkbox's text field that you can enable when the character is under the effects of the Bless spell. The word between the brackets becomes a label that can be seen when you mouse over the roll result in chat. While these Global Modifiers are checked, every roll made from the Attacks & Spellcasting block will add these modifiers to the result.<br />
<br />
====Rolling from the Attacks & Spellcasting Block====<br />
[[File:Poisoned Dagger 5e Roll.png|frame|An attack roll from a +1 Poisoned Dagger]]Rolling from the Attacks & Spellcasting Block is no different than rolling from any other portions of the character sheet. Hovering your mouse over any entry here will highlight its entire label (NAME, ATK, and DAMAGE/TYPE) in red and you'll be able to click on it to roll the attack or spell. You can also drag this entry into the Macro Bar to give yourself easy access to this attack. Because this is a repeating section, the macro name will be a bit messy, but you can right-click the button and rename the macro to whatever you like.<br />
<br />
With any attack that checks for AC, you will see TWO rolls set side by side for the Armor Class check with the name of the attack listed underneath them with the Attack modifier bonus (ATK) appended to the Attack name in light grey. The Roll20 D&D 5E Character Sheet ''always'' rolls for Advantage by default, so you will always have two roll results for this check (most gaming groups use the left roll result if neither Advantage or Disadvantage is being factored in the check). If there is a specified range for the attack, this will be listed above the attack's name.<br />
<br />
Underneath the AC Check and Attack Name is the Damage roll result for the attack. Underneath this roll result will be the Damage Type (ex. slashing, piercing, poison, fire, etc.) listed in light grey italicized font.<br />
<br />
For spells that don't check for AC and instead require a Saving Throws to mitigate or negate the spell's effect, the SPELL DC is listed first. Underneath this, in italicized font, is the effect if a character succeeds the check listed. Underneath the effect is the required attribute saving throw that must be rolled. If Damage is applied, this result is rolled and listed next with its Damage Type.<br />
<br />
[[File:5e_attack_example.gif|right|frame|How to view attack damage when the sheet is set to "Don't Auto Roll Damage"]]<br /><br />
<br />
<br />
{{mbox | text = '''NOTE:''' If your character sheet's Settings have "Auto Damage Roll" set to "Don't Auto Roll Damage" under General Options, the damage will not be listed underneath the AC roll result in chat. The damage was rolled, but presently hidden from view. Anyone can see the damage delivered by manually unfolding the roll result open by hovering your mouse over the roll result in chat and clicking on the attack/spell's name.}}<br />
<div style="clear: both"></div><br />
<br />
===(12) Personality Traits, Ideals, Bonds, and Flaws===<br />
These text fields lock to prevent accidental edits. When a sheet is first created, these fields are unlocked and given a dashed yellow border to the top of the field to showcase that they're editable. To lock the field after entering text, click on the gear icon in the upper right corner of the field. This will remove the yellow border and the field will conform in height to display everything within it.<br />
<br />
There presently isn't a means to format the raw text (italicize, bold, font alignment, etc) within these fields and any line breaks are stripped out. If you ever need to edit the content again while the field is locked, mouse over the desired field and the gear icon will reappear in the top right. Clicking on that will unlock the field once again for edits.<br />
<br />
===(13) Class & Other Resources===<br />
[[File:5E_OGL_Sheet_Resources.png]]<br />
<br />
The Class & Other Resource Blocks can be used to keep track of either an item quantity you have in your equipment (like arrows in a quiver), or skills that don't fit into the other sections on the sheet (like a '''Sorcerer's Sorcery Points''', a '''Cleric's Channel Divinity''' at higher levels, or the number of rounds a '''Barbarian''' has been '''Raging''' so far in a combat encounter).<br />
<br />
There are 3 fields per Block:<br />
* Resource Max:<br />
** The Resource Max field is a text box which allows you to quantify exactly what you're tracking (ex. "Total: 10 Rounds").<br />
* Resource:<br />
** The Resource field is a numeral that you dial up or down or input directly.<br />
* Resource Name:<br />
** The Resource Name is a text box that allows you to label the resource when you click on the light grey "OTHER RESOURCE" label to overwrite it with your own.<br />
**"OTHER RESOURCE" is placeholder text<br />
<br />
<br />
A resource block will be filled automatically if you checkmark an Equipment item as "USE AS A RESOURCE" & the Item Quantity field will be paired with the Resource field in the Resource block & vice versa (you'll need to click outside of the field or hit Enter for changes to refresh across the sheet). If the two resource blocks given by default are not enough then you can add additional blocks by hovering over the section & clicking the "Add" (+ symbol) button.<br />
<br />
The Item Name will also be added to the Resource Name field, however the Resource Max field is apparently not linked to the Item currently.<br />
<br />
If you drag & drop an ammunition item type from the Compendium into your character sheet, the item is added to the Equipment block & is automatically listed & linked as an Other Resource.<br />
<div style="clear: both"></div><br />
To call the first set of class resources use:<br />
* Class Resource <code>@{class_resource}</code><br />
* Other Resource <code>@{other_resource}</code><br />
<br />
<br />
To call the Repeating resources use<br />
* Repeating Resource 1st left<code>@{repeating_resource_$0_resource_left}</code><br />
* Repeating Resource 1st right<code>@{repeating_resource_$0_resource_right}</code><br />
* Repeating Resource 2nd left<code>@{repeating_resource_$1_resource_left}</code><br />
* Repeating Resource 2nd right<code>@{repeating_resource_$1_resource_right}</code><br />
* etc.<br />
<br />
<br />
If you want to do a basic Full Readout of the Repeating Resource, the Format would be (Top Left to Bottom Right):<br />
* Class: <code>@{class_resource_name}: @{class_resource} / @{class_resource|max}</code><br />
* Other: <code>@{other_resource_name}: @{other_resource} / @{other_resource|max}</code><br />
* Left 0: <code>@{repeating_resource_$0_resource_left_name}: @{repeating_resource_$0_resource_left} / @{repeating_resource_$0_resource_left|max}</code><br />
* Right 0: <code>@{repeating_resource_$0_resource_right_name}: @{repeating_resource_$0_resource_right} / @{repeating_resource_$0_resource_right|max}</code><br />
* Left 1: <code>@{repeating_resource_$1_resource_left_name}: @{repeating_resource_$1_resource_left} / @{repeating_resource_$1_resource_left|max}</code><br />
* Right 1: <code>@{repeating_resource_$1_resource_right_name}: @{repeating_resource_$1_resource_right} / @{repeating_resource_$1_resource_right|max}</code><br />
* etc.<br />
<br />
===(14) Tool Proficiencies===<br />
[[File:5E_OGL_Sheet_Tool_Proficiencies.png|left]]The Tool Proficiencies block is for listing a character's Tool Proficiency skills. At the bottom of this block is an "Add" (<span style="font-family:Pictos;">&</span> symbol) button. Clicking this will add a new entry to this block where you can add all of the relative stats for a specific tool proficiency, say Woodcarver's Tools. You can set the level of proficiency to either Proficient, Expertise, or Jack of All Trades. The roll bonus for that tool will reflect the proficiency level selected. Next is an Attribute drop down menu where you can select which character attribute to roll with for a proficiency check. One of the options you can choose is "QUERY ATTRIBUTE" which when you click on the Tool Proficiency to roll it, you will be prompted to choose which attribute you would like to use. The attribute used for the check will be up to the GM when it is time to make the roll check. If there is any additional bonus modifiers that come along with the tool in question, you can input it in the "MODS:" field.<br />
<br />
Once you finished filling out the stats for this tool you can click the <span style="font-family:Pictos;">y</span>(gear) icon at the top right of the entry to hide the stat fields and leaving behind just the rollable button. You can roll by either clicking on this rollable button or dragging it to your [[Macro Bar]].<br />
<br />
You can also use this section to create custom skills or rolls for your campaign setting or home-brew ruleset. Check out the [[#Custom Skills and Stats|Advanced Use]] section for further details.<br />
<br />
====Global Skill Modifier====<br />
You can add a special entry to the Tool Proficiencies & Custom Skills block to handle to global Attacks and Damage modifications to rolls. An example is if the character is under the influence of the Guidance spell and can roll a 1d4 in addition to the result of their skill check. This feature is enabled from the [[#Settings Page|Settings Page]] under General Options. Once enabled, a checkbox will be added at the bottom of the Tool Proficiences & Custom Skills block with a text field to enter the additional die roll.<br />
<br />
For this example, you could enter "1d4[Guidance]" in the global checkbox's text field that you can enable when the character is under the effects of the Guidance spell. The word between the brackets becomes a label that can be seen when you mouse over the roll result in chat. While this Global Modifier is checked, every roll made from the Tool Proficiencies & Custom Skills block and the Skills block will add this modifier to the result.<br />
<div style="clear: both"></div><br />
<br />
===(15) Other Proficiencies & Languages===<br />
[[File:5E OGL Sheet Proficiencies.png|left]]<br />
This block can be set up to be Compendium Compatible (where you can add repeating sections for individual items) or as one resizable free-text field to enter whatever you wish in here. If you don't feel the Tool Proficiency block is needed (as in, you don't feel like your party will ever have to roll individual tool sets), you can store a character's Tool Proficiencies here instead. There presently isn't a means to format the raw text (italicize, bold, font alignment, etc). You can adjust this block's behavior by going to the Settings Page of the sheet and going to the General Options block to change whether this block uses the Simple or Compendium Compatible layout.<br />
<br />
When the Other Proficiences & Languages block is made Compendium Compatible, each repeating field lists a Type selection field and a Proficiency text field. Type has the following options available from its drop down selection menu: Language, Weapon, Armor, Other. <br />
<p style="clear:both;"></p><br />
<br />
===(16) Equipment===<br />
[[File:5E OGL Sheet Equipment.png|framed|right|The Equipment block of the PC Sheet]]<br />
The Equipment block at the bottom of the page has 2 different versions: a Simple version that features a single plain text field where you can track all of your equipment in any format you wish and a Compendium Compatible version that allows you to drag and drop items from the Compendium to automatically populate repeated sections for each indivdual piece of equipment.<br />
<br />
To swap between the two different Equipment block versions, first, go to the sheet's Settings Page (gear icon at the top right of the page) and then to the "General Options" section. Here, on the field labeled "Inventory", you can select between "Simple" or "Compendium Compatible" respectively. Like the name implies, if you want to be able to copy items directly from the Compendium using drag and drop, you must use the Compendium Compatible version. Dragging item entries from the Compendium to the character sheet will add it fully filled in the Equipment section as well as other automated actions described below.<br />
<br />
====Automated Compendium Functionality====<br />
If you populate the Equipment block by dragging and dropping <span style="font-family:Pictos;">i</span> [[Compendium]] items, there are several automatic features that occur when the entries you drag in our equipment items.<br />
Auto-Equip: Every item dragged to the sheet is automatically equipped in the Equipment Section<br />
*'''Weapons:''' A weapon dragged in from the Compendium will add an attack in the Attacks and Spellcasting section for that item.<br />
*'''Armor:''' Armor that is dragged in from the Compendium will add its bonus to the Armor Class (while equipped) section. If you drag multiple pieces of armor to the same sheet and at least two armor entries are equipped at once, a warning will pop up in red at the top of the Equipment Block that the Armor Class isn't being correctly calculated because of the bonus overlap. This warning will dissapear when you unequip down to a single set of armor.<br />
*'''Magical/Wondrous Items:''' Items that modify Attributes, Saves, AC, To Hit, Damage, Spell Attacks, and Spell DC will add that bonus to those elements on the sheet. In most cases, the attribute that is being modified will highlight in blue and followed with an asterisk to showcase that the attribute is being modified by an item. Mousing over the modified number will display the base value of that attribute before the item's modification is applied. This stat modification only applies if the item is equipped in the Equipment section and it will remove its bonus if it is unequipped.<br />
*'''Ammunition:''' Items dragged in from the Compendium that are used for ammunition such as arrows, bolts, darts, and slingstones, will automatically populate and link to an Other Resource field.<br />
<br />
====Manually Adding Items====<br />
You can also add items manually by hovering over the block and clicking the "Add" button (+ symbol). Each equipment entry, by default, show fields for quantity, name, and weight of an item. If you hover over a row and click the small "information" icon (grey-filled circle with a lowercase i centered in it) that appears at the bottom right of the entry you can also set some additional features. <br />
<br />
*'''Equipped Checkbox:''' The checkbox changes the appearance of the Item Name so it's easier to tell what your character currently has equipped from a glance. When left unchecked, the Item Name's font turns grey. When checked, the Item Name becomes a solid black.<br />
*Use As A Resource Checkbox: When checked, this will enable one of the Class Resource blocks and list the item name and its quantity within it. The quantity is tied between the two so changing it in one will be reflected in the other field after clicking outside the field.<br />
*'''PROP:''' This is a text field where you would take note of weapon properties such as ''finesse'', ''versatile'', or ''light''.<br />
*'''MODS:''' This is a text field where you would take note if an item (likely magical) would modify your stats in some fashion such as a character's Attributes, Saves, Skills, AC, To Hit, Damage, Spell Attacks, and Spell DC. If a stat is modified here, its attribute value will become highlighted in blue and adjusted by the supplied modifier listed here. An asterisk is appended to the right of the value to also signify that it has been modified by an item. While your mouse is hovering over the attribute, it will revert back to its unmodified total so you can refer back to its pre-moddified value.<br />
**The format for a stat modification is ''stat name:n'' where n is the stat bonus (ex. ''Strength:21'')<br />
*'''Description Field:''' This is a simple text field to include a description of the particular item and of any special qualities or effects it might have on the player.<br />
Some if not all of these fields will be filled in automatically when adding from the Compendium (where applicable).<br />
<br />
Both versions of the equipment field have the sections for each of the [https://app.roll20.net/compendium/dnd5e/Treasure#h-Treasure coins] you may find on your adventures: copper(CP), silver(SP), electrum(EP), gold(GP), and platinum(PP).<br />
<br />
====Encumbrance====<br />
If you are following Encumbrance rules, the <span style="font-family:Pictos;">i</span> [[Compendium|Compendium Compatible]] Equipment block will automatically calculate and track the weight of your character's backpack if you enter the weight values for any of the items in your Equipment list. When your character becomes encumbered, and depending on its severity, the words ENCUMBERED, HEAVILY ENCUMBERED, or IMMOBILE will display in red underneath the TOTAL WEIGHT value. You can also choose to follow Simple, Variant Encumbrance rules, or not follow Encumbrance rules at all by toggling it off on the [[D&D 5E by Roll20#Settings Page|Settings Page]] under "General Options".<br />
<br />
====Mods====<br />
The Mods field of each piece of equipment can modify the values of ability scores, AC, saving throws, Skill (Ability) checks and more. What follows is a list of the modifiers, and the proper syntax for adding them.<br />
<br />
All modifiers are separated by commas. There are other modifiers that can appear the mod field, used in creating the item from a compendium drag and drop operation, but the modifiers below have live effects on the character sheet, depending on if the item is marked as “equipped”.<br />
<br />
'''replace the <code>+n</code>, with the number you want.''' For example, if you want to boost Animal Handling skill by 3, you look at the table and find <code>Animal Handling +n</code>, so you will add to your item <code>Animal Handling +3</code>.<br />
<br />
{| class="wikitable" <br />
|-<br />
! Modifier<br /><br />
! Effect<br /><br />
|-<br />
| style="width: 20%;" | '''Combat Modifiers'''<br />
| '''These affect items that provide attacks (Appear in the attack section of the character sheet)'''<br />
|-<br />
| Melee Attacks +n<br />
| Adds +n hit "Magic Bonus" to that attack. It is not global, and only affects a weapon(melee or ranged), not an item, staff or other category. The bonus is figured into the attacks display on the 5e sheet.<br />It is NOT ''Melee Attack''.<br />
|-<br />
| Melee Damage +n<br />
| Adds +n damage "Magic Bonus" to that attack. It is not global, and only affects a weapon(melee or ranged), not an item, staff or other category. The bonus is listed separately in the attacks display on the 5e sheet.<br />
|-<br />
| Spell Attack +n<br />
| Adds a global +n to the character's Spell Attack bonus.<br />It is NOT ''Spell Attacks.''<br />
|-<br />
| '''Saving Throws'''<br />
| '''All modifiers stack with “Saving Throws +n'''<br />
|-<br />
| Strength Save +n,<br />Dexterity Save +n,<br />Constitution Save +n,<br />Intelligence Save +n,<br />Wisdom Save +n,<br />Charisma Save +n<br />
| Adds a +n to the indicated saving throw<br />''Do not use a colon.''<br />
|-<br />
| Saving Throws +n<br />
| Adds a Global Modifier to ALL saving throws.<br />
|-<br />
| Spell DC +n<br />
| Adds a global +n to a spell casting character’s Spell Save DC.<br />It is NOT Spell ''Save'' DC.<br />
|-<br />
| '''Ability Scores'''<br />
| <br />
|-<br />
| Strength +n,<br />Dexterity +n,<br />Constitution +n,<br />Intelligence +n,<br />Wisdom +n,<br />Charisma +n<br />
| Provides a bonus to the indicated ability score, which will appear in blue on the sheet while the bonus is active.<br />Do not use a colon. ''Strength: +10'' will do nothing<br />
|-<br />
| Strength n,<br />Dexterity n,<br />Constitution n,<br />Intelligence n,<br />Wisdom n,<br />Charisma n<br />
| Replaces the indicated ability score, which will appear in blue on the sheet while the bonus is active.<br />Do not use a colon. ''Strength: 10'' will do nothing<br />
|-<br />
| '''Skills'''<br />
| <br />
|-<br />
| Acrobatics +n,<br />Animal Handling +n,<br />Arcana +n,<br />Athletics +n,<br />Deception +n,<br />History +n,<br />Insight +n,<br />Intimidation +n,<br />Investigation +n,<br />Medicine +n,<br />Nature +n,<br />Perception +n,<br />Performance +n,<br />Persuasion +n,<br />Religion +n,<br />Sleight of Hand +n,<br />Stealth +n,<br />Survival +n<br />
| Adds the value to the indicated Skill roll. Note that in this case, the <code>+</code> and a colon are optional. <code>Acrobatics +5</code>, <code>Acrobatics 5</code>, <code>Acrobatics: +5</code>, <code>Acrobatics: 5</code> will all add <code>5</code> to the character’s Skill roll. For consistency and to guard against future functionality, it’s probably best to follow the format for ability scores, and use a plus sign with no comma: <code>Acrobatics +5</code>.<br />There is no Global Skill modifier<br />
|-<br />
| '''AC'''<br />
| <br />
|-<br />
| AC +n<br />
| By itself, <code>AC: 13</code> adds 13 to the character’s Armor Class. It does not replace it. <br /><br />If <code>Shield</code>, <code>Light Armor</code>, <code>Medium Armor</code>, or <code>Heavy Armor</code> is also in the mods field, it will change the calculation.<br />''<code>Light Armor, AC: 13</code>'' will give a formula of 13 + dex mod<br />''<code>Medium Armor, AC: 13</code>'' will give a formula of 13 + dex mod (max +2)<br />''<code>Heavy Armor, AC: 13</code>'' will give you flat AC 13<br />''Shield, AC: 13'' would add 13 to the your AC. The Shield keyword is superfluous in this case.<br />''<code>Shield, AC: 2</code>'' will just add 2 to the AC.<br />Finally, a bare modifier, such as for a Ring of Protection can just be written as <code>AC: +2</code> or <code>AC +1</code>.<br /><br />Shield or bare AC bonuses will stack with other armor mods on different items. You cannot equip multiple armors simultaneously, or have a custom armor equation on the settings tab and wear an armor. This will generate a flag.<br /><br />The + and a colon are semi-optional. <code>AC +5</code>, <code>AC: +5</code>, <code>AC: 5</code> will all work. However, <code>AC 5</code> will do nothing. For consistency and to guard against future functionality, it’s probably best to indicate a base AC as <code>AC: n</code> and a Shield as <code>AC +n</code>.<br />At this point, there is no way to differentiate between Ranged AC and Melee AC, though some magic items such as the ''Arrow Catching Shield'' make the distinction.<br />
|}<br />
<br />
<br />
<br />
<div style="clear: both"></div><br />
<br />
===(17) Features & Traits===<br />
[[File:5E OGL Sheet Features Traits.png|thumbnail|left|The Compendium Compatible itemized version of the Features & Traits section]]<br />
The '''Features and Traits '''-block is the place to store '''Class-''', '''Race-''' and '''Background Features''', '''Feats''', and other special notes about your character or of a certain piece of equipment or ability. When using the Charactermancer, the previously mentioned features appears in this section.<br />
<br />
This block can be set up to be <span style="font-family:Pictos;">i</span> [[Compendium|Compendium Compatible]] (where you can add repeating sections for individual items) or as one resizable free-text field to enter whatever you wish in here. You can adjust this block's behavior by going to the [[D&D 5E by Roll20#Settings Page|Settings Page]] of the sheet and going to the '''General Options'''-block to change whether this block uses the Simple or Compendium Compatible layout. <br />
<br />
When adding items to the Compendium Compatible version of this block, you have the <code>Name</code> field, a <code>Source</code>-field where you can choose between (Racial, Class, Feat, Background, or Other) , a <code>Source Type</code>-text field to describe the type, and then the multilined <code>Description</code>-textbox. Clicking on the <span style="font-family:Pictos;">y</span>(gear)-icon in the top right corner of the item will lock/unlock the item's editability. When locked down, a <span style="font-family:Pictos;">w</span>(chat bubble)-icon appears when you mouse over the feature/trait. Clicking on the <span style="font-family:Pictos;">w</span> will share this feature's description in the {{Text Chat}}.<br />
<br />
There presently isn't a means to format the raw text (italicize, bold, font alignment, etc) of the Simple version or in the Description section of either version of the Features & Traits block.<br />
<br />
You can drag-n-drop '''Feats''' from the compendium, even though they can't be selected in the Charactermancer on levelup.<br />
<br />
PC Features and Traits can be called using an ability roll:<br />
<code>%{selected|repeating_traits_$0_output}</code><br />
Simply increase the $0 value to access all Features and Traits listed on the character sheet, $1, $2, $3...<br />
<br />
<p style="clear:both;"></p><br />
<br />
==Bio Page==<br />
[[File:D&D5E-Roll20-BIO-tab.png|right|thumb|250px|The Bio Page of the PC Sheet]]The Bio page, opened by selecting "BIO" from the 4 buttons near the top right of the sheet, is comprised of free-form text fields that can be used to keep track of less "structured" information about your character. You can use this page to describe your character's appearance, keep track of who their allies are and what organizations they've worked for, and on this page is a section to supplement the inventory list, on the front page, with the "Treasure" section, where you can keep track of all the loot you find along your travels.<br />
===Bio Header===<br />
[[File:D&D5E-Roll20-Bio-header.png|550px]]<br /><br />
<br />
The header of the Bio page contains the basic run down of a character's physical appearance.<br />
*'''Character Name:''' This is carried over from every single PC Page and matches the character journal's name<br />
*'''Age:''' The character's current age<br />
*'''Size:''' The size classification for the race type (Medium for most cases)<br />
*'''Height:''' The character's height<br />
*'''Weight:''' The character's weight<br />
*'''Eyes:''' The character's eye color<br />
*'''Skin:''' The character's skin color<br />
*'''Hair:''' The character's hair color/style<br />
<br />
===Character Appearance===<br />
While the Bio Header describes the bare bone physical characteristics of a PC, this field is for fleshing out the visual peculiarities and/or cues of your character. Does you character have a piercing gaze? A stooped posture? Are they fancily dressed or are their clothes moth-eaten? In essence, this field is for everything and anything one would note about the character–from the equipment or garb they wear to how they comport themself.<br />
<br />
===Allies & Organization===<br />
This text field is for listing important or campaign relevant NPCs that the character may have a connection with. It's also for keeping track of faction allegiance. In the case of ''Dungeons & Dragons''' Forgotten Realms world, a PC could be a member of the Harpers or the Emerald Enclave, among other major factions who are all vying for power of the continent.<br />
<br />
===Character Backstory===<br />
This field is for listing your character's pre-campaign history, their relations, and the pertinent places they have been to in the past.<br />
<br />
===Additional Features & Traits===<br />
This text field is a continuation of the [[#.2817.29_Features_.26_Traits | Features & Traits]] section of the Core Page. The section on the Core Page is a good place for commonly utilized features of a character or briefly jotting down an abbreviated list. This field on the Bio page gives you more real estate to fully write down everything you need in whole.<br />
<br />
===Treasure===<br />
This text field is where you can list all the loot you've collected while searching bodies and delving through dungeons. Since much of these effects are transient and are likely to be used, given away, or sold to the highest bidder at the earliest opportunity, this may be preferable place to keep this list of items rather than adding them to the itemized Compendium Compatible Equipment section (if you have that version enabled).<br />
<br />
==Spell Page==<br />
[[File:D&D5E-Roll20-Spells-tab.png|right|thumb|400px|The Spell Page]]The Spell page, opened by selecting the "SPELLS" button from the four buttons near the top right of the sheet, is used to keep track of all of the powerful magics at your character's fingertips.<br />
<br />
===Spell Page Header===<br />
[[File:D&D5E-Roll20-Spells-header.png|550px]]On the Spells page Header you can set the ability modifier that will be used for casting spells. Selecting the Spellcasting Ability block will allow you to select an attribute from a dropdown, and this will be used in all relevant spell rolls. This attribute will be set automatically when you select a spell casting class. The next two blocks, the Save DC and Attack Bonus will be set automatically based on the class that is selected on the Core page.<br />
<br />
===Spellcasting Ability===<br />
The Spellcasting Ability modifier will automatically update, depending on the class you select on the Core page, to the correct ability modifier for your class. If, for some reason, you need to change this value you can click on the modifier listed in this section and it will give you a drop-down list of all available ability modifiers.<br />
<br />
===Spell Save DC & Attack===<br />
The Spell Save DC and Spell Attack Bonus sections cannot be changed manually, but are just a visual output of modifiers that will be happening behind the scenes. The Spell Attack Bonus is the number that will be added to all spell attack rolls, automatically.<br />
<br />
The Spell Save DC refers to the Save DC that enemies will have to beat when they are trying to dodge/resist your incoming spells. Say, Fred the Sorcerer casts Lightning bolt, and his Spell Save DC is 14. Any enemies hit by his attack will have to make a DEX save and try to beat 14. If they manage to beat the attack, then they are only grazed and take half of the damage. If they don't beat 14, then they take the full damage of the attack instead.<br />
<br />
===Spell Levels & Spells Per Day===<br />
The main section of the Spells page lists 10 sections, ranging from 0 to 9, representing the Cantrips (0) and spells level 1 - 9 where the level of the spell is listed in the triangle on the left of each section header. The number in the left square of the header represents the total number of Spell Slots, in other words, the maximum number of times a spell of this level can be cast in between long rests. This number will be set automatically depending on the level of your character, but can be modified by clicking the up or down arrow or just entering a number in the space provided. The number in the right-most box in the headers is the Slots Remaining value that can be used for you to keep track of the number of times you've cast a spell at this level.<br />
<br />
===Adding Spells===<br />
[[File:D&D5E-Roll20-Spells-Icons.png|framed|right]]<br />
When you drag spells from the <span style="font-family:Pictos;">i</span> [[Compendium]] to the sheet, a new spell entry will be added to the Spell Page under the appropriate level header. This will copy over all corresponding information linked to the spell, as well as creating an attack entry in the [[D%26D_5E_by_Roll20#.2811.29_Attacks_.26_Spellcasting|Attacks & Spellcasting]]-block on the "Core" page, if the spell can be used as an attack. The name of the spell will be listed to the left of the entry and to the right are icons for whether the spell is a Ritual (R), requires Concentration (C), and lists whether there is a Verbal (V), Somatic (S), or Material (M). There is also a circle at the far left of the entry that can be toggled to be filled in with red or left empty. This toggle represents spells that are Prepared for the day and are available for a player's convenience to help track this.<br />
<br />
You can manually add spells by selecting the <span style="font-family:Pictos;">&</span> under any of the Spell Level headings. This will present you with a blank template where you can enter all of the information about a spell. By default, the spell card only contains non-attack information about a spell. If the spell IS an attack you can change the "Output" selector from "Spellcard" to "Attack", this will show some additional input fields to fill out the attack information about the spell. Switching this input will also add an attack entry to the [[D%26D_5E_by_Roll20#.2811.29_Attacks_.26_Spellcasting|Attacks & Spellcasting]]-section on the [[#Core Page|Core page]] so this spell attack can also be cast from the main page. All of these sections are linked, so changing information in one place will also change the corresponding information in the other location. To save your edits, click on the gear icon at the upper right of the entry to collapse the spell entry.<br />
<br />
You can edit any spell at any time, by hovering your mouse over the entry to make a <span style="font-family:Pictos;">y</span> icon appear on the left. Clicking on the <span style="font-family:Pictos;">y</span> will roll out the spell once more to be edited.<br />
<br />
==Settings Page==<br />
[[File:D&D5E-by-Roll20-Settings-Page.png|thumb|right|400px|The Settings tab of the sheet, accessed from the '''<span style="font-family:Pictos;">y</span>''' icon ]]<br />
The Settings page, accessed by selecting the <span style="font-family:Pictos;">y</span>(gear) icon from the four buttons near the top right of the sheet, is where you can make changes to some parts of your character sheet that aren't represented on the other pages.<br />
<br />
===Class Options===<br />
In the class options section is where you have access to some important parts of your character, that usually are managed in the background. They are placed here so that, if needed they can be modified as well.<br />
<br />
'''Hit Dice:''' This section will be set automatically depending on the class chosen on the [[#Core Page|Core page]], but can be changed here by selecting the value and choosing a new one from the drop-down menu. This option is used whenever the "Hit Dice" section is used on the Core page.<br />
<br />
'''Carrying Capacity Modifier:''' This modifier allows you to increase the weight that a character can carry before they become encumbered.<br />
<br />
'''Global Magic Attack Modifier:''' This modifier will affect all spell attacks rolled from the sheet.<br />
<br />
'''Magic Caster Level:''' By default, a character's caster level is tethered to their class level. This option allows you to set the caster level manually, so you can have it differ from the character's class level. This will automatically change the Spell Slots Total for each spell level on the [[#Spell Page|Spells page]].<br />
<br />
'''Spell Save DC Mod:''' The Spell Save DC is normally a field you can't edit from the Spell page and is set by the character's class and level. This modifier allows you to alter that value.<br />
<br />
'''Spell Icons:''' This option will allow you to choose to turn off all the Spell Icons (R, C, V, S, & M), show them all, or only display only the ritual and concentration icons.<br />
<br />
'''Halfling Luck:''' Use this checkbox if your character is a Halfling that happens to take advantage of the Halfling Luck race feat. Using this feat will automatically re-roll any 1s rolled for attacks and skills or ability checks/saves.<br />
<br />
'''Arcane Fighter/Rogue:''' These checkboxes can be used to keep track of when your Fighter or Rogue-classed character actually has access to spells.<br />
<br />
===Multiclass Options===<br />
If you are taking advantage of the D&D 5E multiclassing you can keep track of it in this section. Any levels to your character's additional classes must be changed here, and will then be reflected in the header portion of the sheet. Once you've added additional classes in this section, any time you roll Hit Dice from the Core page it will ask you which classes hit dice you wish to use.<br />
<br />
Note: Be sure to not re-include your main class in this section, or your final level calculation will be incorrect.<br />
<br />
===Custom Class Options===<br />
If you are playing a class that is not part of the D&D 5E Compendium, you can input the important class information in this section, and checking the "Use Custom Class" checkbox will replace the main class selection with your custom built class.<br />
<br />
===Spell Slot Modifiers===<br />
This section allows you to manually modify how many spell slots your character has available for each spell level from 1 to 9.<br />
<br />
===Attribute Options===<br />
'''Attribute Modifiers:''' With this section you can manually adjust the individual Attribute Scores for Strength, Dexterity, Constitution, Intelligence, Wisdom, and Charisma.<br />
<br />
'''Initiative Modifier:''' Usually, your initiative modifier is just based off of your DEX modifier, but if you happen to find a magical item that enhances these rolls this is where you will put that bonus. This modifier will be used whenever the [[#.287.29_Armor_Class.2C_Initiative.2C_.26_Speed|Initiative]]-section is rolled on the Core page.<br />
<br />
'''Initiative Style:''' This setting allows you to select whether Initiative will be rolled with Advantage, Disadvantage, or rolled normally with a single d20 (default).<br />
<br />
'''Add DEX Tiebreaker to Initiative:''' If you would like to enable a tie breaker component to Initiative, this checkbox will enable adding your dexterity Attribute Score as a decimal value to your Initiative roll. So if you have a character with a dexterity attribute score of 14, your initiative modifier will change from a 2 to a 2.14.'<br />
<br />
'''Global Armor Class Modifier:''' This setting will modify your armor class and will be taken into account regardless of the equipment the character uses.<br />
<br />
'''Armor Class Tracking:''' There are three options available: The Automatic version that's default to the sheet where it adds 10 + your DEX modifer and then takes any armor equipped into account. A Custom version which expands out a formula upon selection where you can input your own formula for armor tracking, or you can turn Off Armor Tracking entirely. When turned off, you will need to manually adjust the Armor Class field on the Core page.<br />
<br />
===Save Options===<br />
'''Save Modifiers:''' With this section you can manually adjust the individual Save modifiers for Strength, Dexterity, Constitution, Intelligence, Wisdom, and Charisma.<br />
<br />
'''Death Save Modifier:''' A normal death save is usually just a D20 against a dc of 10, but if you're lucky enough to have a bonus to death saves, this is where you will put your bonuses. This modifier will be represented any time a "Death Save" is rolled from the Core page.<br />
<br />
'''Global Saving Throw Modifier:''' If you have an affect that would modify all saving throws, this option makes it easier to adjust your Save modifiers than having to go in and change each one individually. This modifier will be used every time any save is rolled from the sheet.<br />
<br />
===Skill Options===<br />
If your class offers the ability to achieve "Expertise" in a skill, or if you are using a Bard with the "Jack of All Trades" feat, this is where you will make these adjustments. There is also a section to add flat modifiers to any of your skills if your character has an archetype ability like Remarkable Athlete or a feat that adds a flat bonus to a skill. You can add expertise to any skill by clicking the value next to it and choosing "Expertise" from the drop-down menu. If your Bard has the Jack of All Trades feat, you can check the checkbox at the bottom of this section and it will automatically give half of your character's proficiency points to any skill check that doesn't have full proficiency.<br />
<br />
'''Passive Perception Modifier:''' This option will add a bonus to a character's Passive Perception which is not something you can change directly from the Core page of the sheet.<br />
<br />
===General Options===<br />
The General Options section has some important options that deal more with how the sheet works, rather than actual character creation. Most importantly, the NPC checkbox at the top, which will change the sheet to be the NPC version which is shaped to more easily track an NPC's information.<br />
<br />
'''Roll Queries - Always/Toggle/Query/Never Roll Advantage:''' This option will change how advantage is rolled for all attacks. It defaults to always roll advantage, which means that every time an attack is rolled it will roll twice and present the outcome of both rolls. This is useful for both advantage and disadvantage, otherwise you can just choose either the left or the right to be the default roll. Toggle adds a set of buttons at the top of the sheet to manually switch your advantage options between rolls. If Query is chosen, every time a roll is made it will ask you whether or not it's advantage. If Never is chosen, then it will always roll just a single dice per attack roll.<br />
<br />
'''Whisper Rolls to GM:''' Like above, you have the option to Never/Toggle/Query/Always whisper rolls to the GM. When this option is enabled, the attack roll will only be whispered to the GM and not made public.<br />
<br />
'''Auto Damage Roll:''' By default, damage rolls will not be rolled automatically, but only when you click the attack in the chat window. This is useful because you can choose to only roll damage when an attack hits. Using this option you can make the character always roll damage with every attack.<br />
<br />
'''Core Die Roll:''' You can change the core die (by default it is 1d20) to something else entirely here.<br />
<br />
'''Proficiency Bonus:''' By default, the character's Proficiency Bonus is calculated by class level. This setting allows you choose to calculate this bonus via By Level (the default), via a Proficiency Die as described in the Dungeon Master's Guide, or a Custom calculation which rolls out a field to enter a roll formula for the bonus.<br />
<br />
'''Global Save/Skill/Attack/Damage Modifier Field:''' This series of checkboxes will add new entries to the Saving Throws, Tools Proficiencies & Custom Skills, and Attacks & Spellcasting blocks respectively to add global modifiers (like if a character is under the effects of a Bless or Guidance spell). Each entry will have a Global label in grey at the bottom of its entry and a field to enter the modifier bonus. If you include a word in brackets with the bonus formula (ex. "1d4[Bless]"), the word enclosed in the brackets will appear when you mouse over a roll to see it's formula.<br />
<br />
'''Add Character Name to Templates:''' This option allows you to turn this on or off. When it is on, the character's name is listed in the roll template when rolls are made from the sheet. If the character sheet in question is for an NPC, you will likely want to have this off so the rolls don't accidentally show your hand of what sort of monster your party is facing. This setting is off by default.<br />
<br />
'''Auto Level Calculations:''' This option allows you to turn this on or off. When it is on, adjusting the character's class level will automatically update the character's proficiency bonus, Hit Dice, and spell Slot totals (if the class is a spellcaster).<br />
<br />
'''Encumbrance:''' This option dictates how encumbrance is handled on the Equipment block of the Core page. This requires your Inventory to be set to "Compendium Compatible" to automatically calculate and track the weight of your character's backpack if you enter the weight values for any of the items in your Equipment list. When your character becomes encumbered, and depending on its severity, the words ENCUMBERED, HEAVILY ENCUMBERED, or IMMOBILE will display in red underneath the TOTAL WEIGHT value. This setting has three options: Simple Encumbrance Rules, Variant Encumbrance Rules, or not follow Encumbrance rules at all by toggling it off from this.<br />
<br />
'''Inventory:''' With this option allows you to either have your Equipment block be "Compendium Compatible" or "Simple". The Simple version of the Equipment block will give you single text field to log your inventory. The Compendium Compatible version tracks weight, quantity, and attack options in an itemized list for every equipment item you add to the block.<br />
<br />
'''Features & Traits:''' This option can set the Features & Traits block to be either a single text field or a repeated section that will be Compendium Compatible to list traits and features in an itemized list.<br />
<br />
'''Proficiencies & Languages:''' This option can set the Proficiences & Languages block to be either a single text field or a repeated section that will be Compendium Compatible to list traits and features in an itemized list.<br />
<br />
'''Ammo Tracking (API Required):''' When using the 5th Edition OGL Companion API Script in your game (Pro Subscriber feature), you can set attacks to weapons using ammunition to automatically subtract from their tally in their Resource block. So if your character is equipped with a bow, rolling its attack will automatically remove an arrow from its Resource block.<br />
<br />
===Transition Options(outdated)===<br />
{{mbox | text = This feature doesn't seem to exist on the sheet any longer, so the info in this section is outdated}}<br />
<br />
If your campaign previously used the [https://wiki.roll20.net/DnD5e_Character_Sheet#Intro Community Contributed] or [https://wiki.roll20.net/index.php?title=DnD5e_Shaped_Character_Sheet&oldid=11112#General_Information Shaped Legacy] 5th Edition Character Sheets and you are swapping over to this one, we have an automated conversion tool that will clear or merge elements left over from those two sheets. This procedure can only be done ''once'' and can not be undone. It is recommended that you make a copy of your campaign first before attempting a sheet transition.<br />
<br />
There is also a checkbox that hides this feature entirely from the sheet. If you hide this by mistake, you can gain access to it again by creating a new character journal.<br />
<br />
=The NPC Sheet=<br />
''See Also:'' '''[[D&D5E by Roll20 NPC Attributes]]'''<br />
<br />
One of the most useful parts of the D&D 5E by Roll20 Character Sheet is that it contains both a PC sheet ''AND'' an NPC sheet. An NPC doesn't normally require the depth a PC sheet needs, so the NPC sheet is a much more slimmed down character sheet that doesn't require multiple pages like its PC counterpart. You can access this version of the sheet by going to the Settings Page, by clicking the gear icon near the top right of the sheet, and then checking the NPC checkbox. This will switch the sheet to the NPC version. You can switch back at any time by unchecking the NPC option under General Options on the new page.<br />
<br />
==NPC Options==<br />
[[File:5E_OGL_Sheet_NPC_Options.png|right|thumb|250px|The NPC Options Section]]This is the area where all of the NPC's stats will be entered, it covers everything from the NPC's name, to how strong or quick or smart it is, to what languages it speaks. Most of the fields in this section are just text fields used to keep track of information about the NPC. All of the information entered in these fields will be visible in the stat block once the NPC options are hidden. <br />
<br />
<br />
Any text that appears in light grey is placeholder text. It's there to offer you an example of what the content would be for any given field. <br />
<br />
By default, no skill or ability checks will show up in the NPC's stat block. Once you've added a value to the corresponding skill or ability save, they will appear. If for some reason the NPC will have to make a check with a skill or ability it does not have any bonus in, you can enter a 0 as the modifier for that check and it will add it to the list in the stat block below.<br />
<br />
The XP of an NPC auto-calculates based on its given challenge rating.<br />
<br />
If the NPC is a spellcaster, you can check the checkbox beside '''SPELLCASTING NPC''' and this will add a spell list section that utilizes the spell list and its functionality from the PC version of the sheet.<br />
<br />
At default, you can add Traits and Actions in their respective places after the Challenge Rating and XP area of the Stat Block. For Reactions and Legendary Actions, you need to enable them from the NPC Options section. For Reactions, check off the '''HAS REACTIONS''' checkbox. This will add a new sections to the Stat Block for you to add Reactions to. If an NPC is a monster with Legendary Actions then you must enter the number of actions that monster has access to each turn in the '''LEGENDARY ACTIONS:''' field. Once you add a number here, an additional section will appear in the stat block below, where you can add the specific legendary actions that the monster is able to do.<br />
<br />
The NPC sheet supports Compendium drag & drop. If you want to add a new monster to your game just drag the monster from the <span style="font-family:Pictos;">i</span> [[Compendium]]-tab of the [[Sidebar]] and drop it to anywhere on the Tabletop. This will automatically create a new journal entry named the same as the Compendium entry and will copy all of the information on that compendium page directly into the new sheet. If you have purchased any of the Compendium expansions that expands on the available NPCs like the Monster Manual or Volo's Guide to Monster, a token of that NPC will be added to the Tabletop that will have its stats automatically set and linked to the new journal entry.<br />
<br />
{{mbox | text = '''Note:''' If you already have a journal entry in your {{journal}}-tab with the exact same name as the <span style="font-family:Pictos;">i</span> [[Compendium]] entry, the drag and drop will not work as this automation will stop to prevent overwriting existing content the user has already created. If a drag and drop of an NPC Compendium page does not create a journal entry, run a search for that NPC's name in your Journal to see if an entry already exists. If you do not want to delete the older entry, renaming it will allow the drag and drop to work as expected.}}<br />
<br />
===General Options===<br />
Within the NPC Options section, directly below the Legendary Actions field, is the General Options that are featured on the PC Sheet: NPC checkbox, WHISPER ROLLS TO GM, and the AUTO DAMAGE ROLL options. <br />
<br />
*NPC checkbox<br />
*WHISPER ROLLS TO GM<br />
*AUTO DAMAGE ROLL<br />
*NPC NAME IN ROLLS<br />
*ADD DEX TO TIEBREAKER TO INITIATIVE<br />
<br />
Unchecking the NPC checkbox from here will revert the sheet back to the PC Sheet.<br />
<br />
===Hiding NPC Options===<br />
Once all of the desired information has been entered, you can click the <span style="font-family:Pictos;">y</span>(gear) icon at the top right to hide this section. This leaves behind just the NPC's stat block where you can make all of your rolls from. You can re-open this section to edit the information at any time by clicking on the <span style="font-family:Pictos;">y</span> icon again. It's in the same location regardless if you're looking at NPC Options or the NPC stat block.<br />
<br />
==The NPC Stat Block==<br />
[[File:5E OGL Sheet NPC v2.png|right|thumb|250px|An NPC stat block for a griffon]]Following NPC Options is the NPC Stat Block that is built off of what you input in the NPC Options section. This area may look very similar to a stat block you may find in a monster bestiary or published adventure.<br />
<br />
<br />
Any section of the stat block that has a corresponding roll will have click-able text. For example, if the NPC has to make a CON check, you can click the CON attribute to roll a CON check with all of the required modifiers automatically included. If you added a value to one of the skill modifier fields then that skill will show up in the NPC's "Saving Throws" list where you can click it to make a saving throw roll using that skill's modifier.<br />
<br />
The first section of the Stat Block mirrors all the information you added in the NPC Options section. This content is meant exclusively for rolling and can not be edited directly. You will need to change them from the NPC Options section.<br />
<br />
===Traits===<br />
Traits are pieces of information about an NPC that isn't covered by the NPC options section. These are entered directly onto the NPC's stat block. If you click the "<span style="font-family:Pictos;">&</span>" button that appears right below the "Senses/Languages/Challenge Rating" section it will add a blank entry where you can add a single trait for that NPC. Each Trait Entry features a bold title field which is then followed by a larger text box for the description of the trait. You can add any number of Traits for any NPC.<br />
<br />
===Actions===<br />
NPC actions can be used for any number of things. Each entry initially offers an Action Name field as well as a large text field for the Action description. The checkbox for ATTACK, once checked, adds more structured data fields needed for an attack roll (Type, Range/Reach, To Hit bonus, Target, Damage Roll, and Damage Type). To add a new entry you will select the <span style="font-family:Pictos;">&</span> button that appears below the Actions section. Once all of this is complete you can click the <span style="font-family:Pictos;">y</span>(gear) icon at the top of this entry to hide the input fields, leaving just the action text. You can show this information, or roll the attack, in the chat box by clicking the text for the action. If you need to make further modifications to any action you can hover over the row you wish to edit, then click on the <span style="font-family:Pictos;">y</span>(gear) icon again. This will show all of the action information input fields again. You can add any number of Actions for any NPC.<br />
<br />
===Bonus Actions===<br />
NPC bonus actions are typically not listed on the sheet, and are usually referenced in the Traits section. However, if a player wishes to use this section, it is available if the 'Bonus Action' checkbox is selected. The fields work the same as the Actions section.<br />
<br />
===Reactions===<br />
Once enabled from the NPC Options section, a new heading labeled "Reactions" and its relevant section is added to the stat block that allows you to add Reactions. These entries operate just like Traits.<br />
<br />
===Spells===<br />
Once enabled from the NPC Options section, a new heading labeled "Spells" and its relevant section is added to the stat block that allows you to add Spells. These entries will operate identically to how Spells are added and handled on the PC Sheet with the one noted exception that there is only a single column of spell entries. You can drag spells from the Compendium to add spell entries just like you would with the PC's Spell sheet. Any and all spells added to the character sheet are shared between the NPC and the PC versions.<br />
<br />
===Legendary Actions===<br />
If a number value is added to the LEGENDARY ACTIONS field in the NPC Options section, the Legendary Actions heading and section is added at the very bottom of the stat block and lists some verbiage on how many actions are available to be used on a given turn. This number is dictated by what you entered in the NPC Options. These entries operate the same way as Traits.<br />
<br />
==Rolling for Initiative for NPCs==<br />
There are two ways to roll for Initiative on the NPC sheet. You can click on the NPC's Name to roll for Initiative or you can roll from the die icon labeled INIT that is listed to the right of the Armor Class and Hit Points section of the NPC sheet, towards the top. If you have the Turn Tracker tool open, having the NPC token selected while rolling Initiative will automatically add the NPC and its initiative roll to the tracker. Creatures on the GM layer that are added to the tracker in this fashion will have their entries hidden from the players.<br />
<br />
<br />
You can also create a global Macro that will pop up as a Token Action button in the upper left hand corner of the tabletop every time a token is selected. This will allow you to roll without looking at the NPC sheet at all. The macro formula should look just like this:<br />
<br />
<code>%{selected|npc_init}</code><br />
<br />
=Advanced Use=<br />
<br />
===Custom Skills and Stats===<br />
You can set up any number of custom skills or rolls from the [[#Tool Proficiencies|Tool Proficiencies]] section just underneath the skill section on the Core tab. [[#Class & Other Resources|The Resources]] section is also useful for tracking custom stats to your campaign, game setting, or home-brew rules. There are also various options available from the Settings page to modify attributes, skills, saves, spells, and more.<br />
<br />
===Target Roll Buttons===<br />
A useful way for GMs and Players to reference their abilities is by dynamically setting up a handful of macros that can be used on a token linked to a character, rather than having to roll directly from the sheet. To do this, you'll set up a global macro from the {{Collections}}-tab. You can also write these directly in the {{Text Chat}}.<br />
<br />
In the examples, the <code>selected</code> part can be replaced with <code>target</code>, a character's name, or it's character ID.<br />
<br />
Here are some examples:<br />
<br />
'''PC'''<br />
* Attributes: <code>%{selected|strength}</code>, <code>%{selected|strength_save}</code> | Will roll the Strength Check and Strength Save for the selected [[token]](if the [[Link Token|token is linked to a sheet]])<br />
* <code>%{selected|acrobatics}</code><br />
* <code>%{selected|initiative}</code><br />
* <code>%{selected|death_save}</code><br />
* <code>%{selected|hit_dice}</code><br />
<br />
'''NPC'''<br />
* <code>%{selected|npc_init}</code><br />
* <code>%{selected|npc_str}</code><br />
* <code>%{selected|npc_stealth}</code><br />
* <code>%{selected|npc_hpformula}</code><br />
====Dynamic References to Repeating Sections====<br />
The example we'll be using today is setting up the 1st NPC action:<br />
<code>%{selected|repeating_npcaction_$0_npc_action}</code><br />
Now whenever you use this macro it will roll the first NPC action of whichever NPC token you have selected. You can set up a roll for each action by incrementing the 0 by 1 for each action you wish to add (I.E. <code>$1</code>, <code>$2</code>, <code>$3</code>). Here is a list of important repeating section rolls and their formulas:<br />
<br />
* Player Attack/Spell Attack <code>%{selected|repeating_attack_$0_attack}</code><br />
* Player Attack/Spell Damage <code>%{selected|repeating_attack_$0_attack_dmg}</code><br />
* Player Attack/Spell Critical Damage <code>%{selected|repeating_attack_$0_attack_crit}</code><br />
* Player Global DMG mod <code>%{selected|repeating_damagemod_$0_global_save}</code><br />
** Attr names: <code>global_damage_name</code>, <code>global_damage_damage</code>, <code>global_damage_critical_damage</code>, <code>global_damage_type</code><br />
* Proficiencies <code>%{selected|repeating_proficiencies_$0_output}</code><br />
* Tool/Custom Skill <code>%{selected|repeating_tool_$0_tool}</code><br />
* Traits/Feats: <code>%{selected|repeating_traits_$0_output}</code><br />
<br />
* Spellbook Cantrip <code>%{selected|repeating_spell-cantrip_$0_spell}</code><br />
* Spellbook Level 1 <code>%{selected|repeating_spell-1_$0_spell}</code><br />
* Spellbook Level 2 <code>%{selected|repeating_spell-2_$0_spell}</code><br />
* Spellbook Level 3 <code>%{selected|repeating_spell-3_$0_spell}</code><br />
* Spellbook Level 4 <code>%{selected|repeating_spell-4_$0_spell}</code><br />
* Spellbook Level 5 <code>%{selected|repeating_spell-5_$0_spell}</code><br />
* Spellbook Level 6 <code>%{selected|repeating_spell-6_$0_spell}</code><br />
* Spellbook Level 7 <code>%{selected|repeating_spell-7_$0_spell}</code><br />
* Spellbook Level 8 <code>%{selected|repeating_spell-8_$0_spell}</code><br />
* Spellbook Level 9 <code>%{selected|repeating_spell-9_$0_spell}</code><br />
<br />
'''NPC'''<br />
* NPC Traits/Abilities<code>%{selected|repeating_npctraits_$0_npc_roll_output}</code><br />
* NPC Actions/Attacks<code>%{selected|repeating_npcaction_$0_npc_action}</code><br />
* NPC Attack Damage<code>%{selected|repeating_npcaction_$0_npc_dmg}</code><br />
* NPC Attack Critical Damage<code>%{selected|repeating_npcaction_$0_npc_crit}</code><br />
* NPC Bonus Actions<code>%{selected|repeating_npcbonusaction_$0_npc_action}</code><br />
* NPC Legendary Actions<code>%{selected|repeating_npcaction-l_$0_npc_action}</code><br />
* NPC Mythic Actions<code>%{selected|repeating_npcaction-m_$0_npc_action}</code><br />
* NPC Spells<code>%{selected|repeating_spell-npc_$0_spell}</code><br />
<br />
===Directly Referencing Attributes===<br />
You can discover the name of most of the attributes in the sheet by hovering over them. After a couple of seconds a title will pop up and tell you how to referencing them. You can call attributes in an Ability Rolls by using <code>@{attributename}</code>. If you want to directly reference it in a roll that isn't saved on the sheet, you need to specify the character's name, or use either the <code>selected</code> or <code>target</code> key works.<br />
<br />
'''Examples:'''<br />
* <code>/em attempts to grapple and gets [[1d20+@{strength_mod}]]</code> custom [[Journal#Attributes_.26_Abilities_Tab|Ability call]], saved on the A&A-tab<br />
* <code>/r 1d20+@{Alice|strength_mod}+@{Alice|pb}</code> macro that calls a specific character<br />
* <code>/em have @{selected|hp} out of @{selected|hp|max} left.</code> macro that uses stats from a token(token must be selected before rolling)<br />
* <code>The Enemy's AC is @{target|npc_ac}</code> macro prompt the user to select a target token on the map, and uses it's stats.<br />
<br><br />
<br />
See [[Macros#Attribute_Macros]] for further general details/examples on the syntax.<br />
====PC====<br />
Here are a list of some of the more important stats:<br /><br />
<br />
'''Attributes/Saves:'''<br />
<br />
* Str: <code>strength, strength_mod, strength_save_bonus</code><br /><br />
* Dex: <code>dexterity, dexterity_mod, dexterity_save_bonus</code><br /><br />
* Con: <code>constitution, constitution_mod, constitution_save_bonus</code><br /><br />
* Int: <code>intelligence, intelligence_mod, intelligence_save_bonus</code><br /><br />
* Wis: <code>wisdom, wisdom_mod, wisdom_save_bonus</code><br /><br />
* Cha: <code>charisma, charisma_mod, charisma_save_bonus</code><br />
<br><br />
'''Skills:'''<br />
<br />
<code>athletics_bonus<br /><br />
acrobatics_bonus<br /><br />
animal_handling_bonus<br /><br />
arcana_bonus<br /><br />
deception_bonus<br /><br />
history_bonus<br /><br />
insight_bonus<br /><br />
intimidation_bonus<br /><br />
investigation_bonus<br /><br />
medicine_bonus<br /><br />
nature_bonus<br /><br />
perception_bonus, passive_wisdom<br /><br />
performance_bonus<br /><br />
persuasion_bonus<br /><br />
religion_bonus<br /><br />
sleight_of_hand_bonus<br /><br />
stealth_bonus<br /><br />
survival_bonus<br /><br />
</code><br />
<br />
'''AC, Proficiency, HD etc'''<br />
<br />
<code>pb</code>(Proficiency Bonus)<br><br />
<code>inspiration</code><br><br />
<code>ac<br /><br />
initiative_bonus<br /><br />
speed<br /><br />
hp, hp|max, hp_temp<br /><br />
hit_dice, hit_dice|max, hitdietype<br /><br />
weighttotal<br /><br />
</code><br />
<br />
'''Spells'''<br />
<br />
<code>spell_save_dc, spell_attack_bonus<br /><br />
lvl1_slots_total, lvl1_slots_expended<br /><br />
lvl2_slots_total, lvl2_slots_expended<br /><br />
lvl3_slots_total, lvl3_slots_expended<br /><br />
lvl4_slots_total, lvl4_slots_expended<br /><br />
lvl5_slots_total, lvl5_slots_expended<br /><br />
lvl6_slots_total, lvl6_slots_expended<br /><br />
lvl7_slots_total, lvl7_slots_expended<br /><br />
lvl8_slots_total, lvl8_slots_expended<br /><br />
lvl9_slots_total, lvl9_slots_expended<br /><br />
</code><br />
<br />
Spells, repeating sections:<br><br />
<code>repeating_spell-cantrip<br><br />
repeating_spell-1<br><br />
repeating_spell-2<br><br />
repeating_spell-3<br><br />
repeating_spell-4<br><br />
repeating_spell-5<br><br />
repeating_spell-6<br><br />
repeating_spell-7<br><br />
repeating_spell-8<br><br />
repeating_spell-9</code><br> <br />
<br />
Cantrip stats(most should also work for lvl.1-lvl.9):<br><br><br />
Full statname is spell level + (rowID or row number) + attribute name, e.g. <code>repeating_spell-1_$0_spellname</code> is the spell name of your first Lvl 1 spell, <code>repeating_spell-4_$1_spelldescription</code> is the description of your second lvl.4 spell.<br />
<br />
<code>spellname<br><br />
spellrange, spellcastingtime, spelltarget, spellduration<br><br />
spellschool<br><br />
spellritual<br><br />
spellconcentration<br><br />
spellcomp_v, spellcomp_s, spellcomp_m<br><br />
spellcomp_materials<br><br />
spell_ability<br><br />
spelloutput<br><br />
spellattack<br><br />
spelldamage, spelldamagetype, spelldamage2, spelldamagetype2<br><br />
spellhealing<br><br />
spelldmgmod, spell_damage_progression<br><br />
spellsave, spellsavesuccess<br><br />
spelldescription<br><br />
spellclass, spellsource</code><br />
<br />
'''Items'''<br><br />
<code>cp sp ep gp pp</code><br><br />
(copper pieces, silver, gold, electrum, platinum)<br />
<br />
<code>repeating_inventory_$#_itemcount<br><br />
repeating_inventory_$#_itemname<br><br />
repeating_inventory_$#_itemweight<br><br />
repeating_inventory_$#_equipped<br><br />
repeating_inventory_$#_useasresource<br><br />
repeating_inventory_$#_hasattack<br><br />
repeating_inventory_$#_itemproperties<br><br />
repeating_inventory_$#_itemmodifiers<br><br />
repeating_inventory_$#_itemcontent</code><br><br />
<br />
* <code>equipped</code>, <code>useasresource</code>, <code>hasattack</code> are checkboxes, with value 1 if checked.<br />
* <code>itemmodifiers</code> is for of item changes any stats, like <code>AC +2</code> adding +2 to AC when equpped.<br />
* <code>itemcontent</code> is the item description<br />
<br><br />
'''The class_resource and the other_resource'''<br><br />
<br />
<code>class_resource</code> and <code>other_resource</code> are static resources. That is to say, you need to keep in mind that they are NOT a part of the repeating section, even though it definitely looks that way on the character sheet.<br><br />
<br />
You use these to access them<br />
<br />
<code>class_resource</code><br><br />
<code>class_resource_max</code><br><br />
<code>class_resource_name</code><br><br />
<code>other_resource</code><br><br />
<code>other_resource_max</code><br><br />
<code>other_resource_name</code><br><br />
<br />
'''The repeating resources'''<br><br />
<br />
Any resources that appear beneath the "class resource" and the "other resource" are a part of the "repeating resources" section. This section is known for being confusing for beginners, so it deserves a bit of clarification.<br />
<br />
First, keep in mind that this is one section (not two sections, as people often think), and that "repeating_resource" is its section prefix.<br />
<br />
Second, keep in mind that you need to skip past the row with the "class resource" when you're figuring out the address of the row that you want to refer to. So basically, if you want to refer to the row that is directly below the row that contains the "class_resource", then you would add "_$0" (to form "repeating_resource_$0". And then the next row is "_$1", and so on.<br />
<br />
Third, keep in mind that if you add "_resource_left" (to form "repeating_resource_$0_resource_left"), then you are specifying that you are talking about the CURRENT VALUE of the leftmost resource in that row. And if you add "_resource_left_max", then you are specifying that you are talking about the MAX VALUE of the leftmost resource in that row.<br />
<br />
Here is a complete list of all the fields that you can access in the "repeating_resource" section. Just replace the "#" character with which row you want to access.<br />
<br />
<code>repeating_resource_$#_resource_left</code><br><br />
<code>repeating_resource_$#_resource_left_max</code><br><br />
<code>repeating_resource_$#_resource_left_name</code><br><br />
<code>repeating_resource_$#_resource_right_max</code><br><br />
<code>repeating_resource_$#_resource_right</code><br><br />
<code>repeating_resource_$#_resource_right_name</code><br><br><br />
<br />
<br />
'''Features/Class Traits'''<br />
<br />
<code>repeating_traits_$0_output<br><br />
repeating_traits_$#_name<br><br />
repeating_traits_$#_source<br><br />
repeating_traits_$#_source_type<br><br />
repeating_traits_$#_description<br><br />
</code><br />
<br />
'''Other/Settings:'''<br />
<br />
<br><br />
<code><nowiki>wtype</nowiki></code> (whisper type, can have one of these values:)<br />
* <code><nowiki></nowiki></code> (empty for never whisper)<br />
* <code><nowiki>@{whispertoggle}</nowiki></code> (show the buttons on sheet that can toggle between options)<br />
* <code><nowiki>?{Whisper?|Public Roll,|Whisper Roll,/w gm }</nowiki></code><br />
* <code><nowiki>/w gm</nowiki></code> (always whisper)<br />
<br />
<br />
'''Global modifiers'''<br />
<br />
* <code>repeating_savemod_$0_global_save_roll</code><br />
* <code>repeating_skillmod_$0_global_skill_roll</code><br />
* <code>repeating_tohitmod_$0_global_attack_roll</code><br />
* <code>repeating_damagemod_$0_global_damage_damage</code><br />
<br />
====NPC====<br />
Some stats are the same as for PCs<br />
<br />
<code>npc_name<br><br />
npc_ac<br><br />
hp, hp|max<br><br />
npc_speed<br><br />
npc_challenge<br><br />
npc_xp</code><br />
<br />
Attributes: <code>strength_base, strength_mod</code> (same as PCs)<br />
Saves:<br />
<br />
<code>npc_str_save_base</code>,<code>npc_dex_save_base</code>, <code>npc_con_save_base</code>,<code>npc_int_save_base</code>,<code>npc_wis_save_base</code><code>npc_cha_save_base</code><br />
Skill bonus:<code>npc_acrobatics_base</code>, <code>npc_animal_handling_base</code> etc.<br />
<br />
Damage/Conditions stuff:<br />
<br />
<code>npc_vulnerabilities<br><br />
npc_resistances<br><br />
npc_immunities<br><br />
npc_condition_immunities</code><br />
<br />
Spells:<br />
<br />
<code>npcspellcastingflag</code> (set to "1" if caster, empty otherwise) <br />
<code>spellcasting_ability</code><br />
<code>globalmagicmod </code> (global magic attack modifier)<br />
<code>caster_level</code><br />
<code>spell_dc_mod</code> (spell save DC mod)<br />
<br />
Spells are identical to PC section<br />
<br />
Other:<br />
whisper is same as PCs<br />
<br />
<code>npc_name_flag</code> (show/hide npc name in rolls, value is either <code><nowiki>{{name=@{npc_name}}}</nowiki></code> or <code>0</code>)<br />
<br />
<br />
<sup>Note: anything with the Suffix of <code>|max</code> requires some form of Prefix, such as <code>selected|</code> making the call for such a thing look something along the lines of <code>@{selected|hp|max}</code>. The <code>|max</code> Suffix specifically calls the box on the right of the selected Attribute's Line, for example, you could fill in the Weight Total's 2nd Box with <code>@{strength}*15</code> & whenever you call <code>@{selected|weighttotal|max}</code> it will tell you your 5e standard Maximum Carry Capacity for your current Strength Score.<br />
<br />
===Custom AC Items===<br />
You can add pieces to your inventory and manually give them AC or magic bonuses that will figure into their calculations automatically. Inside the item options is a section for "MODS:". Add <code>Ac +1</code> to add an armor class bonus.<br />
<br />
===Roll Templates===<br />
''Main Article:'' '''[[D&D 5e by Roll20 Roll Templates]]'''<br />
<br />
The '''D&D5E by Roll20''' Character Sheet also includes a series of [[Roll Templates]] that you can use to dress up your own custom macros. Roll Templates provide additional layout and styling options for the display of roll results.<br />
<br />
{{ex}}<br />
[[File:5e-rolltemplate-ex1-2021.png|200px|right|none]]<br />
Rolls stealth for selected npc token, using it's stealth proficiency.<br />
<code><nowiki>/w gm &{template:npcatk} {{attack=1}} {{name=Shadow}} {{rname=Shadow Stealth}} {{rnamec=Hide}} {{r1=[[@{selected|d20}+@{selected|npc_stealth} + 6]]}} {{always=1}} {{r2=[[@{selected|d20}+@{selected|npc_stealth} + 6]]}} {{description=While in dim light or darkness, the shadow can take the Hide action as a bonus action. Its stealth bonus is **also** improved to +6 }}</nowiki></code><br />
<br />
===Magic Missile Spell===<br />
{| role="presentation" class="wikitable mw-collapsible mw-collapsed" style="float:right; margin-left: 10px;margin-right: 60px;"<br />
| Image of the Spell's settings<br />
|-<br />
| [[File:Magic-Missile-5E-2020.png|right|frame|The Magic Missile Spell]]<br />
|}<br />
<br />
RAW, Magic Missile is rolled once, and the single roll is then used for each hit. So by default the spell rolls <code>1d4+1</code>. (See [[Talk:D&D 5E by Roll20#Old Magic Missile Discussion]] for more info.)<br />
<br />
You can modify the spell to instead roll 3d4+3 at first level, and then in the ''HIGHER LVL CAST DAMAGE'' section, set it to <code>1d4+1</code>.<br />
<br />
To automatically use higher-level spell slots with Magic Missile, you have to write a 0 into the ''HIGHER LVL CAST DAMAGE'' section of the spell and select any die. It will show the box for selecting higher-level spell slots when launching Magic Missile, but since it multiplies the higher-level damage cast by 0, the added roll doesn't show up in the chat, making it roll a single die for every missile while using any level spell slot.<br />
<br />
=API=<br />
{{pro only|section}}<br />
[[API:Introduction|API Scripts]] allow for greater customization and functionality to how Roll20 operates beyond what it can do at default. This section will list some info on using various APIs that interact with the character sheet.<br />
<br />
Example of APIs from the One-Click Install menu, that designed to be used with the '''D&D 5E by Roll20''' sheet:<br />
* '''5E BattleMaster'''<br />
* '''5E Resting in Style'''<br />
* '''CashMaster'''<br />
* '''Concentration'''<br />
* '''[[Script:It's a Trap|It's a Trap! -- D&D 5E Generic]] (should detect automatically what sheet is used)<br />
** {{repo|Roll20/roll20-api-scripts/tree/master/ItsATrap_theme_5E_Generic#readme readme}}<br />
* '''ShortRest'''<br />
* '''SpellMaster'''<br />
* '''WildShape'''<br />
<br />
A good number of the more general APIs have built in settings for configuring them for usage with the 5E sheet, such as '''GroupInitiative''', '''GroupCheck''', '''Experience Tracker''', '''[[PowerCards]]''' <br />
<br />
* '''[[GroupCheck]]:''' <code>!group-check-config --import 5E-OGL</code> will configure the API for use with this sheet<br />
* '''[[GroupInit|GroupInitiative]]:''' before use, API need to be configured for the sheet, either through the menu preset, or using the command: <code>!group-init --add-group --Bare </code><br />
* '''CombatMaster:''' is by default configured with conditions for D&D 5E<br />
* '''[[ChatSetAttr]]:''' API that can create, edit, & delete stats on sheets. Example: [[Script:ChatSetAttr#Add_new_thing_to_Repeating_Section|Adding a new magic item to a sheet]], with one chat command <br />
* '''[[Script:Ammo]]''' can be used for updating ammo & spellslots when used<br />
<br />
==Utilizing the ''5th Edition OGL by Roll20 Companion'' API Script==<br />
'''{{repo|Roll20/roll20-api-scripts/tree/master/5th%20Edition%20OGL%20by%20Roll20%20Companion 5th Edition OGL Companion}}'''is an official companion script for the "D&D 5E by Roll20" character sheet. The Companion currently supports Ammo Tracking, Automatic NPC Tokens, Automatic Death Save Tracking, and Automatic Spell Slot Tracking. <br />
<br />
{{mbox | text = Installing & creating [[API]] Scripts is a {{Pro}} feature. In order to be able to access these advanced scripts, the [[GM]] of the campaign must be a [[Pro]] subscriber and enable it for their campaign.}}<br />
<br />
<br />
'''''How to Add the API Script to your Game'''''<br />
<br />
If you have a PRO account, you can install the API script by going to your game's Campaign Page and clicking on the '''Settings''' button, and then choosing '''API Scripts'''. This brings you to the API Scripts page for your current game. The Companion Script is part of the One-Click Community API Installation options. Under the Script Library tab, there is a drop down menu that lists all the available community created scripts. Scroll down till you find the '''System Toolbox''' category and select the "5th Edition OGL by Roll20 Companion" script. The version number, the script's author, and a brief description of what the script does will appear right below the drop down menu once it is selected. Below that, click on the blue "Add Script" button to add the script to your game.<br />
<br />
<br />
'''''List of API commands for the 5th Edition OGL Companion API Script'''''<br />
* <code>!5ehelp</code> - Gives a list of the script's API commands in the chat tab.<br />
* <code>!5estatus</code> - Lists the current status of the script's features in the chat tab.<br />
* <code>!ammotracking on/off/quiet</code> - Automatically expends linked resource when attack is made<br />
* <code>!autonpctoken on/off</code> - Automatically generates a NPC token on the GM's screen based on the default token when an NPC's health calculation is rolled<br />
* <code>!deathsavetracking on/off/quiet</code> - Automatically ticks off successes and failures when death saves are rolled, clearing on death, stabilization, or hp recovery<br />
* <code>!longrest <character name></code> - This will add Hit Dice recover and if spelltracking is on, this command will reset all of the character's spell slots to unspent.<br />
* <code>!npchp <character name></code> - Rolls NPC hit point totals using their formula and updates the token bar. If no character name is provided it will roll the selected tokens.<br />
* <code>!spelltracking on/off/quiet</code> - Automatically expends spell charges as cast, factoring in higher level casting, and spells marked as Rituals will not spend a spell slot.<br />
<br />
<br />
Options:<br />
* ''on'' - Toggles the functionality on (default)<br />
* ''off'' - Disables the functionality<br />
* ''quiet'' - Maintains functionality while preventing results from being output to the chat.<br />
<br />
<br />
===Automatic Ammunition Tracking===<br />
''Main Article:'' '''[[D&D 5E by Roll20: How to setup Ammunition and Resource tracker]]'''<br />
<br />
Automatic Ammunition Track is a feature that requires the above Companion API Script. Once installed, follow these instructions to enable automatic ammunition tracking in your game:<br />
<br />
This example sets up a Longbow with a quiver of Arrows to track.<br />
# On the Settings (Gear Icon) tab of a character sheet, under GENERAL OPTIONS, make sure that the INVENTORY option is set to "Compendium Compatible" and not "Simple".<br />
# While still under GENERAL OPTIONS, set the AMMO TRACKING feature to ON.<br />
# Create manually or drag a missile weapon (ex. Longbow) from the Compendium to your sheet.<br />
# Create manually or drag a missile type (Arrows) from the compendium to your sheet<br />
# Expand the missile type (Arrows) by clicking on the "I" information icon that appears when hovering the mouse over the item.<br />
# Select the USE AS RESOURCE checkbox. (ammunition items dragged from the Compendium will have this option automatically checked off)<br />
# On the CORE tab, expand the missile weapon (Long Bow) in the ATTACKS & SPELLCASTING section by clicking on the gear icon that appears when hovering over the attack.<br />
# In the AMMUNITION section put the exact name of the ammunition resource (Arrows). If you want to spend more than one piece of ammunition per shot you want to add the number of pieces after the name of the ammunition resource and a comma. (ex. ''Arrows,2'' )<br />
<br />
<br />
Now, any time the missile weapon (Longbow) is rolled, a piece of ammunition will automatically be spent and the chat will make note. Additionally after the first time the missile weapon is used the AMMUNITION section will update with the ID of the resource repeating section, this is normal and expected.<br />
<br />
<br />
===Automatic Spell Slot Tracking===<br />
<br />
Automatic Spell Slot Tracking is a feature that requires the above Companion API Script. Once installed, follow these instructions to enable automatic spell slot tracking in your game:<br />
* In the chat input area of the Sidebar, type ''!5estatus'' and press Enter, to check if spelltracking is set to 'on'.<br />
* If not, type ''!spelltracking on'' and press Enter to activate this feature.<br />
* Alternatively, you may type ''!spelltracking quiet'' and press Enter to activate this feature, while preventing spelltracking messages from being displayed in the chat.<br />
<br />
<br />
<br />
Once the Spell Slot Tracking has been activated, each time a spell is cast:<br />
# The number of cast spells of the appropriate level is updated in the Spell tab of the character sheet (see [[5th Edition OGL by Roll20|Spell Levels & Spells Per Day]]).<br />
# A message is output in the chat, displaying the spell level, the number of available spell slots and the number of used spell slots for this level.<br />
# Spell slots decrement as spells are cast. <br />
# Spells that are marked as a Ritual do not affect the tally of spell slots when cast.<br />
<br />
<br />
At any time, you can manually adjust this count directly in the Spell Page of the character sheet.<br />
<br />
=Updates=<br />
* {{hc|articles/360037772613-Change-Log Roll20 Changelog}} - Full Changelog of Roll20, updates for 5E sheet are included<br />
* {{fpl|10096810/ D&D 5th Edition by Roll20 (Q2Y2021)}} often has mentions of latest updates<br />
* Major Sheet Updates:<br />
** Feats can now be selected in Charactermancer {{fpl|8891809 June 2020}}<br />
** Game [[creator]] can select which [[compendiums]] are or aren't accessible in a game. [https://app.roll20.net/forum/post/8738570/release-note-for-may-26-2020 May 26 2020]<br />
<br />
=Known Issues=<br />
The sheet has a number of known bugs and issues, some which are mentioned in the sheet's latest forum thread.<br />
<br />
'''Charactermancer/Character Creation'''<br />
* '''Charactermancer & Compendium drag-n-drop doesn't work when sheet is in a separate window.''' This is [[Character_Sheets#Character_Sheet_in_a_separate_window|an inherit limitation to how character sheets work]] at the moment. <br />
* '''Multiclassing & spell selection''' - There are troubles when multiclassing spellcasters and getting to select spells from the right lists.<br />
* '''Duplicate races/classes from Essential Kit appear in selection''' You need to uncheck EK from your compendium for it to no longer appear in selections.<br />
<br />
<br />
'''General:'''<br />
* '''Warlock spell slots''' - The Warlock's spell slots don't work too well with the sheet, and most people use some manual adjustments for how they work. The number of spell slots also appears wrong in the Charactermancer.<br />
* '''NPC stat <code>desc</code> changed into <code>description</code>''' This was a recent update that broke some macros for people, resulting in error messages along: "can't find ''desc'' attribute" {{fpl|8297517/ release notes march 2020}}<br />
<br />
=Sheet Guides=<br />
* [[5E Macros]]<br />
* {{blog|638339117446578176/tome-of-tips-dungeons-dragons-5th-edition-ogl Tome Of Tips: The D&D 5E character sheet}}<br />
* {{yt.be|9BGGr97qJdY|Learning Roll20: EP01 Character Sheets (D&D 5E)}} 50min, by Roll20 (2020)<br />
<br />
=Related Pages=<br />
* D&D 5E by Roll20 sheet<br />
** [[D&D5E by Roll20 NPC Attributes]]<br />
** [[D&D 5e by Roll20 Roll Templates]]<br />
** [[D&D 5E by Roll20: How to setup Ammunition and Resource tracker]]<br />
* [[5E]] - general D&D 5E info for Roll20. Lists also the alterantive character sheets for 5E<br />
* [[D&D]] - Roll20 stuff on the various editions.<br />
* {{Compendium}}<br />
** [[Compendium Sharing]]<br />
* [[Character Vault]]<br />
<br />
=See Also=<br />
* {{repo|Roll20/roll20-character-sheets/tree/master/DD5thEditionLegacy Sheet sourcecode}} - (Public version of sheet code is 1½+ years behind from what is actually used)<br />
* {{hc|articles/360037772613-Change-Log Roll20 Changelog}} - Full Changelog of Roll20, updates for 5E sheet are included<br />
<br /><br />
<br /><br />
[[Category:Character Sheet Documentation]]<br />
[[Category:Official Sheet]]<br />
[[Category:DnD5E]]<br />
[[Category:Featured articles]]</div>5004103https://wiki.roll20.net/Script:ScriptCardsScript:ScriptCards2021-10-01T11:00:28Z<p>5004103: /* Repeating Section Access (--R) */</p>
<hr />
<div>{{revdate}}<br />
== Introduction ==<br />
'''ScriptCards''' provides a script interpreter that can be used to create powerful macros that display the results of player/NPC actions, or display other information in a pleasing visual format in your game's chat window. The scripting language contains variables (both dice-roll (enhanced numerics) and strings) as well, conditionals, branching, subroutines with parameters, and a set of built-in functions to simplify working with Roll20 information.<br />
{{script overview<br />
|name=ScriptCards<br />
|author={{user profile|2365448|Kurt J.}}<br />
|code=<br />
|version=1.4.0e<br />
|lastmodified=2021-09-24}}<br />
ScriptCards is not game-system specific, and can be used with any system/sheet. Near the end of this Wiki there is a section set aside for libraries that can implement system-specific tasks, with the hope that enthusiasts playing particular systems will create and share utility functions that can be utilized by the wider community.<br />
<br />
The default display style for ScriptCards output is similar to the format used to document player and NPC abilities in Dungeons and Dragons 4th Edition, but does not have any system ties to D&D4E.<br />
<br />
Current OneClick Version : 1.4.0e<br />
<br />
Current Development Version : 1.4.4<br />
<br />
'''''<big>Critically Important: ScriptCards does not use/parse inline rolls. ScriptCards includes its own built-in dice roll parser to allow for the use of variables inside dice rolls. As of version 1.2.3, ScriptCards will now take inline rolls and substitute the total result value in statement strings, meaning that you can utilize inline rolls but ScriptCards will only see the result of the roll, and not parse the roll components itself.</big>'''''<br />
<br />
* {{fpl|9752053/ ScriptCards thread}}<br />
** {{fpl|10000297/ Scritpcard API Working and Sharing}}<br />
* https://github.com/kjaegers/ScriptCards/tree/main/ScriptCards_API - GitHub repository for source before the one-click version is updated.<br />
* {{yt.be|hyR7Jnq4mQM ScriptCards Intro}} 45min, Jan 2021<br />
* {{yt.be|u50xvNzS9Zk ScriptCards Magic Missile Deep Dive}} 39min, Feb 2021<br />
<br />
<br />
__TOC__<br />
=== Is ScriptCards Related to [[PowerCards]]? ===<br />
<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
Check the '''[[#What to Know if you are Coming from PowerCards|What to Know if you are Coming from PowerCards]]'''-section for a comparison table between the two scripts.<br />
<br />
== What is a ScriptCard Script ==<br />
<br />
A ScriptCard Script is text written into the chat window (either typed directly, pasted, or run via a macro) that will produce a card of information in the [[text Chat|chat window]]. A ScriptCard Script is composed of an [[API]] command: <code><nowiki>!scriptcard {{ }}</nowiki></code> enclosing any number of lines that determine the output that will be added to the card. At it simplest, the following macro:<br />
<br />
<pre>!scriptcard {{ }}</pre><br />
<br />
Will produce just a title card that displays “ScriptCards” as the name:<br />
<br />
[[File:Scriptcard blank.png]]<br />
<br />
Of course, this is just the simplest type of macro and isn’t very useful. In order to produce useful output, we need to include lines between the <code><nowiki>{{</nowiki></code> and <code><nowiki>}}</nowiki></code> that direct the API script as to what it should do.<br />
<br />
== Structure of a ScriptCard Line ==<br />
<br />
All ScriptCard lines begin with two dashes, followed by an ''statement identifier character'' that lets ScriptCards what type of line it is. There are several of these, and they are detailed in the next section. After the line type identifier, a Tag name 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.<br />
<br />
Following the Tag is a vertical bar, and then the content of the line itself. Again, each type of line might interpret this content differently.<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Identifier !! Statement Type !! Tag !! Content !! Notes<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--/</nowiki> || Comment || unused || unused || The <code>--/</code> 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--#</nowiki> || 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").<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--+</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--=</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--&</nowiki> || Assign String 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. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--@</nowiki> || 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 (i.e., [[TokenMod|!token-mod]], or [[ChatSetAttr|!setattr]], etc.)<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--:</nowiki> || 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<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--^</nowiki> || Branch To || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--></nowiki> || Call Procedure || 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<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--<</nowiki> || 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.<br />
|- <br />
| style="white-space:nowrap" | <nowiki>--?</nowiki> || Conditional Branch || Condition to be evaluated || True Branch Label<nowiki>|</nowiki>False Branch Label || The condition will be evaluated and execution will jump to one of the two indicated branches (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 included a semicolon separated list of parameters. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--s</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--l</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--v</nowiki> || 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+'''''<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--e</nowiki> || Echo to Chat || Name to send chat command as || Chat message to send || Variable substitution takes place on the tag and content.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--R</nowiki> || Retrieve Repeating Section Row information || "find", "first", or "next" || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--~</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--c</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--i</nowiki> || Information Request || User Prompt;Button Caption || InfoType;VariableName;ParameterText || See full documentation below.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--d</nowiki> || 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. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--%</nowiki> || 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. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--*</nowiki> || 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.<br />
|}<br />
<br />
== ScriptCard Statement Type Details ==<br />
The sections below detail the individual statement types supported by ScriptCards<br />
<br />
=== Comment (--/) ===<br />
<br />
A --/ statement is ignored by the ScriptCards parser. You can use this type of statement to add comments and informational text to your script. <br />
<br />
Example:<br />
<pre><br />
!script {{<br />
--/|Script Name : Fireball<br />
--/|Purpose : Allow the player to cast a fireball and blow stuff up!<br />
.<br />
.<br />
.<br />
}}<br />
</pre><br />
<br />
=== Set Parameter (--#) ===<br />
<br />
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.<br />
<br />
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.<br />
<br />
'''''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.'''''<br />
<br />
Examples:<br />
<pre><br />
--#title|Magic Missile<br />
--#leftsub|Level 1 Spell<br />
--#rightsub|Force Damage<br />
</pre><br />
<br />
The three examples above set the “title”, “leftsub”, and “rightsub” values for the card to the content value for the line. <br />
<br />
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.<br />
Settings Lines do not produce output lines on the card.<br />
<br />
The following settings are available (note that parameter names are ''not'' case sensitive):<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Name !! Effect/Use !! Default Value !! Type<br />
|-<br />
| 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<br />
|-<br />
| allowplaintextinrolls || If set to a non-zero value, plain character text in rolls will be copied to the roll text || 0 || Per-Line<br />
|-<br />
| bodyFontFace || Name of the font used in the card rows || Helvetica || Global<br />
|-<br />
| bodyFontSize || Size of the text in the card rows || 14px || Global<br />
|-<br />
| bodybackgroundimage || Specify an image (content for a CSS background-image tag) for the body area || none || Global<br />
|-<br />
| buttonBackground || Background color for buttons created with [button][/button] || #1C6EA4 || Per-Line<br />
|-<br />
| buttonBorderColor || Border (outline) color for buttons created with [button][/button] || #999999 || Per-Line<br />
|-<br />
| buttonFontFace || Font Family specifier for captions on buttons created with [button][/button] || Tahoma || Per-Line<br />
|-<br />
| buttonFontSize|| Text size for captions on buttons created with [button][/button] || x-small || Per-Line<br />
|-<br />
| buttonTextColor|| Text color of labels on buttons created with [button][/button] || #FFFFFF || Per-Line<br />
|-<br />
| 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<br />
|-<br />
| deferralcharacter || Changes the meta script deferral sequence to the specified value || ^ || Per-Line<br />
|-<br />
| diceFontColor|| Color of the dice created with the [d4] [d6], etc. formatting markers || #1C6EA4 || Per-Line<br />
|-<br />
| dicefontsize || Size of the dice created with the [d4] [d6], etc. formatting markers || 3.0em || Per-Line<br />
|-<br />
| 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<br />
|-<br />
| disablerollprocessing || If set to a non-zero value, --= lines will not process dice rolls strings || 0 || Per-Line<br />
|-<br />
| emoteBackground || Background color of the emote area || #f5f5ba || Global<br />
|-<br />
| emoteFont || Name of the font used in emote area (above the title of the output card) || Georgia || Global<br />
|-<br />
| emoteFontColor || Color of the font in the emote area || None (Empty) || Global<br />
|-<br />
| emoteFontSize || Size of the font used in the emote area || 14px || Global<br />
|-<br />
| emoteFontWeight || Font weight for the font in the emote area || bold|| Global<br />
|-<br />
| emoteState || If set to anything other than "visible", the emote portion of the card will not be displayed || visible || Global<br />
|-<br />
| emoteText || Text to display in the emote portion of the card || None (Empty) || Global<br />
|-<br />
| emotefont || Name of the font used in the emote text area || font-family: Georgia, serif; font-weight: bold; || Global<br />
|-<br />
| evenRowBackground || Hex code for the background color for even rows || #eeeeee || Per-Line<br />
|-<br />
| evenRowFontColor || Hex code for the text color for even rows || #000000 || Per-Line<br />
|-<br />
| evenrowbackgroundimage || Specify an image (content for a CSS background-image tag) for the even card rows || none || Per-Line<br />
|-<br />
| executionlimit || Maximum number of script lines the interpreter will try to execute. This prevents "infinite loop" sandbox crashes || 40000 || Global<br />
|-<br />
| hideCard || If set to any non-default value, the entire card output will be suppressed || 0 || Global<br />
|-<br />
| 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<br />
|-<br />
| 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<br />
|-<br />
| lineheight || Vertical size of each line on the output card || normal || Per-Line<br />
|-<br />
| nominmaxhighlight || If set to anything other than "0", rolls will not display crit/fumble/mixed highlight colors. || 0 || Per-Line<br />
|-<br />
| norollhighlight || If set to anything other than "0", rolls will not be formatted (plain numbers) but will still get a tooltip with details ('''''v1.3.6b+''''') || 0 || Per-Line<br />
|-<br />
| oddRowBackground || Hex code for the background color for even rows || #d0e4f5 || Per-Line <br />
|-<br />
| oddRowFontColor || Hex code for the text color for odd rows || #000000 || Per-Line<br />
|-<br />
| oddrowbackgroundimage || Specify an image (content for a CSS background-image tag) for the odd crd rows || none || Per-Line<br />
|-<br />
| reentrant || Used to name a script for rentrant button use || 0 || Global<br />
|-<br />
| 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)0 || Global<br />
|-<br />
| rollhilightlineheight || Determines the height of the hilight box placed around roll results ('''''1.4.2+''''') || 1.0em || Per-Line<br />
|-<br />
| roundUp || If set to a non-default value, integer division will round up instead of down || 0 || Per-Line<br />
|-<br />
| showfromfornonwhispers || If set to a non-zero value, will include the sender on cards that aren't whispered || 0 || Global<br />
|-<br />
| 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<br />
|-<br />
| subtitleFontColor || Color of the text in the subtitle areas || #FFFFFF || Global<br />
|-<br />
| subtitleFontFace || Name of the font used on the subtitle sections || Tahoma || Global<br />
|-<br />
| subtitleFontSize || Size of the subtitle font || 13px || Global<br />
|-<br />
| subtitleSeperator || The character(s) that will be placed between leftsub and rightsub || <nowiki>&#x2666</nowiki>; || Global<br />
|-<br />
| tableBorderRadius || CSS specifier for how rounded the borders of the output card are. Use "0px;" for square borders || 6px; || Global<br />
|-<br />
| tableShadow || CSS specifier for the drop shadow under the output card || 5px 3px 3px 0px #aaa; || Global<br />
|-<br />
| tablebgcolor || Background color of the whole card. '''''Normally not visible''''' || #EEEEEE || Global<br />
|-<br />
| tableborder || Color of the border that surrounds the whole card || 2px solid #000000; || Global<br />
|-<br />
| 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<br />
|-<br />
| timezone || IANA Specifier for the local time zone, used in system/date functions || merica/New_York || Per-Line<br />
|-<br />
| title || Text displayed in the title area of the card || ScriptCards || Global<br />
|-<br />
| titleCardBackground || A hex color code representing the background color of the title area. || #1c6ea4 || Global<br />
|-<br />
| titleFontColor || Color of the text on the card title || #FFFFFF || Global<br />
|-<br />
| titleFontFace || Name of the font used on the title area || Contrail One || Global<br />
|-<br />
| titleFontLineHeight || Line spacing on the title area || 1.2em || Global<br />
|-<br />
| titleFontSize || Size of the title font || 1.2em || Global<br />
|-<br />
| titlecardbackgroundimage || Specify an image (content for a CSS background-image tag) for the title card area || none || Global<br />
|-<br />
| titlecardbottomborder || Border CSS specifier for the bottom of the title card area || 2px solid #444444; || Global<br />
|-<br />
| titlecardgradient || If set to non-zero value, will place a vertical gradient on the title card area || 0 || Global<br />
|-<br />
| usehollowdice || If set to a non-zero value, the hollow/outline versions of the dice fonts will be used || 0 || Per-Line<br />
|-<br />
| whisper|| Comma separated list of who to whisper the output to. Use "gm" for [[GM|GMs]] and "self" for the sender || none || Global|}<br />
|}<br />
<br />
''Setting Lines do not produce output lines on the card''<br />
<br />
=== Direct Output (--+) ===<br />
<br />
A direct output line display 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.<br />
<br />
Examples of Direct Output lines:<br />
<pre><br />
--+Hello|World<br />
--+Attack|The monster rolls [$Attack] to hit!<br />
--+Damage|@{target|token_name} is hit for [$Damage] [#3333AA][b]frost[/b][/#] damage.<br />
</pre><br />
<br />
Direct Output lines support inline formatting, roll variable replacement, character attribute references, and procedure variables.<br />
<br />
=== GM Output (--*) ===<br />
<br />
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. <br />
<br />
Example:<br />
<pre><br />
--+PlayerLine|This line is shown on the public card<br />
--*GMLine|This line will only be shown to GMs, on a separate card.<br />
</pre><br />
<br />
=== Roll Variable Assignment (--=) ===<br />
<br />
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.<br />
<br />
'''''All components of a roll equation should be separated with spaces.'''''<br />
<br />
Examples:<br />
<pre><br />
--=MissileDamage|1d4 + 1<br />
--=Attack|1d20 + @{selected|strength_mod} [STR] + @{selected|pb} [PROF]<br />
</pre><br />
<br />
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. Text enclosed in square brackets ([]) is considered "flavor text" and will be added to the result text but does not impact the roll result.<br />
<br />
The following dice formats are supported:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Format Pattern !! Example !! Description<br />
|-<br />
| XdY || 3d8 || Simple format. Roll a Y-sided die X times<br />
|-<br />
| XdYkhZ || 2d20kh1 || Roll Y-sided die X times and keep the highest Z number of dice<br />
|-<br />
| XdYklZ || 4d6kl3 || Roll Y-sided die X times and keep the lowest Z number of dice <br />
|-<br />
| XdY>Z || 5d6>3 || Roll Y-sided die X times and count a 1 for each roll greater than Z <br />
|-<br />
| XdY<Z || 5d6<3 || Roll Y-sided die X times and count a 1 for each roll less than Z <br />
|}<br />
<br />
'''''Note: The dice formulae below are supported in the development version of ScriptCards and will be merged with the table above when activated on OneClick'''''<br />
::{| class="wikitable"<br />
|-<br />
! Format Pattern !! Example !! Description<br />
|-<br />
| 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<br />
|-<br />
| 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<br />
|-<br />
| 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)<br />
|-<br />
| 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<br />
|}<br />
<br />
The following operators are supported in a roll equation:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Operator !! Operation<br />
|-<br />
| + || Addition <br />
|-<br />
| - || Subtraction <br />
|-<br />
| * || Multiplication <br />
|-<br />
| / || Division <br />
|-<br />
| \ || Integer Division (Rounds down) <br />
|-<br />
| % || Modulo (Remainder of Divison)<br />
|}<br />
<br />
Roll Variables can be accessed at any time after they have been created by using the [$VariableName] format, with the following optional modifiers:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Modifier !! Meaning<br />
|-<br />
| No modifier || In a Direct Output Line (<nowiki>--+</nowiki>) 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<br />
|-<br />
| .Total || The end result of the roll equation as an unformatted number <br />
|-<br />
| .Base || The cumulative result of any dice rolled in the Roll Text (Numeric modifiers are not included) <br />
|-<br />
| .Ones || The number of dice in the roll that came up as 1s <br />
|-<br />
| .Aces || The number of dice in the roll that came up as the maximum number on the die <br />
|-<br />
| .Odds || The number of dice in the roll that came up with an odd number <br />
|-<br />
| .Evens || The number of dice in the roll that came up with an even number <br />
|-<br />
| .RollText || The raw text of the roll that was use to generate the results <br />
|-<br />
| .Text || A text representation of the results of the roll, including the numbers rolled for each die <br />
|-<br />
| .tableEntryText || The text portion of the result of a table roll<br />
|-<br />
| .tableEntryImgURL || The image source portion of the result of a table roll<br />
|-<br />
| .tableEntryValue || Numeric value of tableEntryText (via parseInt). If a non-numeric value, will be 0<br />
|-<br />
| .Raw || The total numeric result without any formatting, even if placed somewhere formatting would normally be done. <br />
|}<br />
<br />
Examples:<br />
<pre><br />
--+Total Damage|[$MissileDamage.Total] (roll was 1d4+1)<br />
--+Base Damage|[$MissileDamage.Base] (without the +1)<br />
--=Attack|1d20 + @{selected|strength_mod} [STR] + @{selected|pb} [PROF] + [$BlessBonus] [Bless]<br />
</pre><br />
<br />
In this case, 1d4 will be rolled and stored in “BlessBonus”, which can then be used in the Attack line.<br />
<br />
'''''Mathematical Functions in Roll Expressions '''''<br />
<br />
The ScriptCards roll parser works from left to right, always maintaining a current value and applying whatever comes next to the total. The following in-line functions to the roll parser. These are:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Expression !! Meaning<br />
|-<br />
| {ABS} || Absolute Value<br />
|-<br />
| {CEIL} || Ceiling value (round up to the next whole number)<br />
|-<br />
| {FLOOR} || Floor value (round down to the next whole number)<br />
|-<br />
| {ROUND} || Round value (round up if the decimal portion is greater than 0.5, otherwise round down)<br />
|-<br />
| {NEGATE} || Multiply the value by negative one.<br />
|-<br />
| {SQRT} || Take the square root of the running value. ('''''1.4.1+''''')<br />
|-<br />
| {SQUARE} || Square the running value. ('''''1.4.2+''''')<br />
|-<br />
| {CUBEROOT} || Take the cube root of the running value. ('''''1.4.2+''''')<br />
|-<br />
| {CUBE} || Cube the running value. ('''''1.4.2+''''')<br />
|-<br />
| {SIN} || Return the SIN of running value. ('''''1.4.2+''''')<br />
|-<br />
| {COS} || Return the COS of running value. ('''''1.4.2+''''')<br />
|-<br />
| {TAN} || Return the TAN of running value. ('''''1.4.2+''''')<br />
|-<br />
| {ASIN} || Return the ASIN of running value. ('''''1.4.2+''''')<br />
|-<br />
| {ACOS} || Return the ACOS of running value. ('''''1.4.2+''''')<br />
|-<br />
| {ATAN} || Return the ATAN of running value. ('''''1.4.2+''''')<br />
|}<br />
<br />
<br />
'''''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 <nowiki>[[ ]]</nowiki> 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.<br />
<br />
'''''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.<br />
<br />
'''Rolling on Rollable Tables'''<br />
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.<br />
<br />
''Roll Variable Lines do not produce output lines on the card.''<br />
<br />
=== String Variable Assignment (--&) ===<br />
<br />
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:<br />
<br />
<pre><br />
--&MyText|Hello<br />
</pre><br />
<br />
Here, we assign the text "Hello" to the string variable named MyText. You can also append text to a string variable by prefixing the content with a + sign:<br />
<br />
<pre><br />
--&MyText|+ World<br />
</pre><br />
<br />
If run after the statement above, MyText will now contain "Hello World".<br />
<br />
String variables can be referenced using the syntax [&variablename]<br />
<br />
=== Call API (--@) ===<br />
<br />
ScriptCards can use a Call API instruction to execute other API commands. The Tag contains the API 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 API command is executed.<br />
<br />
Examples:<br />
<pre><br />
--@eh|list<br />
--@alter|_target|@{target|token_id} _bar|3 _amount|-[$Damage]<br />
</pre><br />
<br />
In the first example above, the command <code>!eh list</code> will be executed, calling [[EncounterHelper]]. In the second, {{fpl|1216260/ AlterBars}} is called to modify a token's Bar 3 value.<br />
<br />
'''''Note:''''' When ScriptCards (or any API script) runs other API 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).<br />
<br />
See [[API:Script Index]] for more options.<br />
<br />
=== Branch Label (--:) ===<br />
<br />
A branch label defines a line in your code that can be reached by one of the branching instructions (<nowiki>--^</nowiki>, <nowiki>--></nowiki>, or <nowiki>--?</nowiki>). The Tag serves as the label name, and must be unique on the card.<br />
<br />
The vertical bar (|) separator must be present, but the content portion of the line is unused and can be treated as a comment.<br />
<br />
Examples:<br />
<pre><br />
--:MyLoop|<br />
--:CriticalHit|Will jump here if we roll a critical hit!<br />
</pre><br />
<br />
''A Branch Label line does not produce an output line on the card.''<br />
<br />
=== Branch (--^) === <br />
<br />
A Branch line 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.<br />
<br />
Examples:<br />
<pre><br />
--^MyLoop|Jumps to MyLoop<br />
--^SkipCrit|We didn't crit, so skip the Crit code<br />
</pre><br />
<br />
''A Branch line does not produce an output line on the card.''<br />
<br />
=== Call Procedure (-->) ===<br />
<br />
Similar to a branch, a Call Procedure (sometimes knows 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 (<nowiki>--<</nowiki>) 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 (;).<br />
<br />
Examples:<br />
<pre><br />
-->FixFormat|#3333FF;#999999<br />
</pre><br />
<br />
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%].<br />
<br />
=== Return (--<) ===<br />
<br />
A return instruction marks the end of a Gosub procedure. 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.<br />
<br />
Examples:<br />
<pre><br />
--<|<br />
--<|End of MySub<br />
</pre><br />
<br />
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.<br />
<br />
=== Conditional Statement (--?) ===<br />
<br />
A conditional statement contains some equation in the Tag that will be evaluated. '''''If any part of the comparison can/does contain a space, it needs to be surrounded by double quotes'''''<br />
<br />
Based on the true/false result of the evaluation, one of two execution paths will be taken. These execution paths are detailed in the content section of the statement. The "if true" path is specified first (directly after the vertical bar), and the "if false" path is specified after it, also separated by a vertical bar.<br />
<br />
Example:<br />
<pre><br />
--?[$AttackRoll.Total] -ge [$TargetAC]|Hit|Miss<br />
</pre><br />
<br />
'''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.'''<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Branch Format !! Meaning<br />
|-<br />
| Label || If just a label is specified, execution will branch to that label when the comparison is matched.<br />
|-<br />
| >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 <br />
|-<br />
| =VariableName || The roll variable "VariableName" will be assigned the value following a semicolon (ex: --?1 -eq 1|=Roll;1d20)<br />
|-<br />
| &VariableName || The string variable "VariableName" will be assigned the value following a semicolon (ex: --?1 -eq 1|&Result;Hit|&Result;Miss)<br />
|-<br />
| % or %! || The current for...next loop will perform the "next" action (%) or will break out (%!) <br />
|-<br />
| [ || Code block (see below)<br />
|}<br />
<br />
Examples:<br />
<pre><br />
--?[$AttackRoll.Base] -eq 20|CriticalHit<br />
--?[$AttackRoll.Base] -eq 1|>Fumble;@{selected|dexterity_mod}<br />
--?"@{target|npc_type}" -inc "undead"|&MonsterType;Undead|&MonsterType;Not Undead<br />
--?[$Attack.Total] >= [$ArmorClass]|>Hit|>Miss<br />
</pre><br />
<br />
In the first example, if the Base value of AttackRoll is a 20 (natural 20 on the die) execution will branch to the CriticalHit label.<br />
<br />
In the second example, 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%].<br />
<br />
The third example looks for the word "undead" in the npc_type attribute of the targeted character. If it exists in the text, the MonsterType string variable will be set to "Undead", otherwise it will be set to "Not Undead". <br />
<br />
The final example would call 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.<br />
<br />
''Text that does/may contain a space should be enclosed in double quotes.''<br />
<br />
The following comparison operators are available:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Comparator !! Meaning<br />
|-<br />
| -eq || Equal To <br />
|-<br />
| -eqi || Case insensitive Equal To <br />
|-<br />
| -ne || Not Equal To <br />
|-<br />
| -nei || Case insensitive Not Equal To <br />
|-<br />
| -gt || Greater Than <br />
|-<br />
| -ge || Greater Than or Equal To <br />
|-<br />
| -lt || Less Than <br />
|-<br />
| -le || Less Than or Equal To <br />
|-<br />
| -inc || Includes (text strings). <br />
|-<br />
| -ninc || Does Not Include (text strings). <br />
|}<br />
<br />
Multi-part conditionals are supported with -and and -or as separators. For example:<br />
<br />
<pre><br />
--?[$Attack.Total] -ge @{target|npc_ac} -and [$Attack.Base] -ne 20|HitButNotCrit<br />
</pre><br />
<br />
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):<br />
<br />
true AND false OR true<br />
<br />
Will be evaluated as true. The first two (true and false) will be false, but then false OR true will be true.<br />
<br />
Conversely:<br />
<br />
true or false and false<br />
<br />
Will be false, because the first true and false will evaluate to true, and then true and false will be false.<br />
<br />
'''CODE BLOCKS'''<br />
<br />
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.<br />
<br />
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:<br />
<br />
<pre><br />
!script {{<br />
--=Roll|1d2<br />
--+Roll|[$Roll]<br />
--?[$Roll.Total] -eq 2|[<br />
--&Value|Yep!<br />
--+|We are inside the TRUE portion of the block<br />
--]|[<br />
--&Value|Nope<br />
--+|We are inside the FALSE portion of the block<br />
--]|<br />
--+After|the blocks!<br />
--+Value|[&Value]<br />
}}<br />
</pre><br />
<br />
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 --]|. <br />
<br />
At this time, blocks cannot be nested, and can only be created as part of a conditional (--[ is not a valid statement type)<br />
<br />
''A conditional statement does not produce a line of output on the card.''<br />
<br />
=== Case Statement (--c) ===<br />
<br />
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 (:). Each match condition includes a branch label that will be used if the test value matches the item. 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:<br />
<br />
<pre><br />
!script {{<br />
--#title|Case Statement Testing<br />
--=Roll|1d4<br />
--C[$Roll.Total]|1:>One;[$Roll]|2:>Two;[$Roll]|3:>Three;[$Roll]|4:>Four;[$Roll]<br />
--X|<br />
<br />
--:One| --+Value|was One ([%1%]) --<|<br />
--:Two| --+Value|was Two ([%1%]) --<|<br />
--:Three| --+Value|was Three ([%1%]) --<|<br />
--:Four| --+Value|was Four ([%1%]) --<|<br />
}}<br />
</pre><br />
<br />
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 variable as a parameter.<br />
<br />
=== Save and Load (--s and --l) ===<br />
<br />
This statement pair is used to either store (--s) or load (--l) data from persistent storage. Items stored in persistent storage remain between card rolls and between Roll20 sessions. There are two types of data that can be stored: settings and roll variables. <br />
<br />
Examples:<br />
<br />
<pre><br />
--Ssettings|GreenStyle<br />
--Srollvariables|FirstCardVars<br />
</pre><br />
<br />
In this case, the tag for the statement determines what type of item is being saved (settings or rollvariables). When saving settings, all non-default settings are written to the named setting storage value. When Roll Variables are saved, all variables that currently exist will be saved to the named storage value.<br />
<br />
Loading stored items simply requires the same command with the --l statement type:<br />
<br />
<pre><br />
--Lsettings|GreenStyle<br />
--Lrollvariables|FirstCardVars<br />
</pre><br />
<br />
When loading settings, all stored settings will be applied to the current card settings. You can override settings by changing them after the load.<br />
<br />
When loading roll variables, the saved variables will be added to (or overwrite if they have the same name) any variables on the current card. This means it is safe to create roll variables before the load statement.<br />
<br />
'''Practical Uses'''<br />
The major intended use of persistent storage is for storing card formats for use in later scripts. For example, the following script:<br />
<br />
<pre><br />
!scriptcard {{<br />
--#titlecardbackground|#22CC22<br />
--#oddrowbackground|#cceecc<br />
--#evenrowbackground|#99ee99<br />
--Ssettings|@{selected|token_name}<br />
}}<br />
</pre><br />
<br />
Would save the titlecardbackground, oddrowbackground, and evenrowbackground settings to a saved list named after the selected token's name. When creating cards for that token to run later, you could include the line:<br />
<br />
<pre><br />
--Lsettings|@{selected|token_name}<br />
</pre><br />
<br />
To load all of the settings at once. By creating these setting sets for each character, you can specify a different color scheme for each character that can then be used in cards with a single formatting line.<br />
<br />
There is a supplemental ! command added to support saved settings:<br />
<br />
<pre><br />
!sc-liststoredsettings<br />
</pre><br />
<br />
Will produce a list of all stored setting names, with buttons to list the setting values stored in each group and a button to delete groups as needed.<br />
<br />
=== Visual Effects (--v) ===<br />
<br />
The --v statement can be used to create visual effects on the tabletop. The tag portion of the statement can be either "token" or "betweentokens". The content portion of the statement contains the required parameters for the effect generation, separated by spaces. If the effect is "none", no effect will be played. If any other value that doesn't match a Roll20 effect name will result in a burst-fire effect.<br />
<br />
For "token" effects, the parameters are the token id for the token the effect happens on, followed by the effect specifier.<br />
<br />
Example:<br />
<pre><br />
--vtoken|@{selected|token_id} burst-fire<br />
</pre><br />
<br />
For "betweentoken" effects, the parameters are the source token id, the target token id, and the effect specifier.<br />
<br />
Example:<br />
<pre><br />
--vbetweentokens|@{selected|token_id} @{target|token_id} beam-magic<br />
</pre><br />
<br />
'''''Version 1.2.8+'''''<br />
<br />
An additional effect specifier, "point" is available in 1.2.8+. This specifier allows you to create a visual effect at a designated X/Y pixel coordinate. Future updates will add custom-vfx support to this option. The parameters are the X and Y coordinates and the effect descriptor. As of version 1.2.9, you can also use custom effect specifiers with Point effects:<br />
<br />
<pre><br />
--vpoint|150 200 burst-fire<br />
</pre><br />
<br />
=== Echo to Chat (--e) ===<br />
<br />
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.<br />
<br />
Example:<br />
<pre><br />
--eThe Ghost|/em hovers around @{selected|character_name}... BOO!<br />
</pre><br />
<br />
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).<br />
<br />
'''''Whispering'''''<br />
<br />
You can use the echo statement to send a whisper, but there's a trick to it. If you execute this code here:<br />
<br />
<pre><br />
--eThe Ghost|/w ExamplePlayerName Boo.<br />
</pre><br />
<br />
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.<br />
<br />
So, in conclusion, it's best to use something like this when you're sending a whisper:<br />
<br />
<pre><br />
!script {{<br />
--#hidecard|1<br />
--&sender|The Ghost<br />
--&receiver|ExamplePlayerName<br />
--&message|Boo.<br />
--e[&sender]|/w [&receiver] [&message]<br />
--eScriptCards|/w gm **Whispered from [&sender] to [&receiver]:** [&message] <br />
}}<br />
</pre><br />
<br />
This will ensure that the message appears in your chat feed as well.<br />
<br />
=== Repeating Section Access (--R) ===<br />
<br />
ScriptCards (as of v0.0.13) supports accessing repeating section rows on a character sheet (for example: the attacks, the items, and the repeating resources) with the --R statement type. <br />
<br />
There are three basic commands you can use with --R, and they are specified by the tag used:<br />
<br />
'''''The "find" tag'''''<br />
<br />
An Rfind statement is used to search through a repeating field. Here is the general form of such a statement.<br />
<br />
<pre><br />
--Rfind|characterid;EntryName;SectionPrefix;SearchField<br />
</pre><br />
<br />
This is the most direct way to access a repeating section row. Supplying the character ID, followed by what you are looking for (Greatsword, for example), followed by the character sheet's section prefix (repeating_attack), followed by the field to check what you are searching for (atkname) will load the matching section (if found) into the script parsers memory. For example:<br />
<br />
<pre><br />
--Rfind|@{selected|character_id};Greatsword;repeating_attack;atkname<br />
</pre><br />
<br />
Will look at the character's "repeating_attack" section for an entry with an atkname value equal to "Greatsword". Similarly:<br />
<br />
<pre><br />
--Rfind|@{selected|character_id};Bite;repeating_npcaction;name<br />
</pre><br />
<br />
Will look for a "Bite" action on an NPC's action list.<br />
<br />
'''''The "first" tag'''''<br />
<br />
<pre><br />
--Rfirst|characterid;section prefix<br />
</pre><br />
<br />
This form of the --R command will look at all of the entries in the specified repeating section and load the first one into memory:<br />
<br />
<pre><br />
--Rfirst|@{selected|character_id};repeating_attack<br />
</pre><br />
<br />
Would load the character's first "repeating_attack" row into memory.<br />
<br />
'''''The "next" tag'''''<br />
<br />
<pre><br />
--Rnext|<br />
</pre><br />
<br />
No parameters are required for --Rnext, which loads the next entry in the list that was obtained with "first" into memory.<br />
<br />
'''''The section prefixes for the 5E by roll20 character sheet'''''<br />
<br />
Can somebody please add a list of them here?<br />
<br />
'''''Additional information'''''<br />
<br />
However a row is obtained, it will be parsed to replace any attribute references (ie, @{level}) with the corresponding character attribute.<br />
<br />
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".<br />
<br />
You can reference repeating attribute data using the syntax [*R:attributename] syntax (similar to referencing standard character attributes).<br />
<br />
Here are some examples:<br />
<br />
Display the details of the "Greatsword" PC attack:<br />
<br />
<pre><br />
!script {{<br />
--Rfind|@{selected|character_id};Greatsword;repeating_attack;atkname<br />
--+Attack Name|[*R:atkname]<br />
--+Base Damage|[*R:dmgbase]<br />
}}<br />
</pre><br />
<br />
[[File:Scriptcards repeating greatsword.png|Repeating Greatsword Attack]]<br />
<br />
List all of the actions an NPC can take (just actions, not legendary, etc.)<br />
<br />
<pre><br />
!script {{<br />
--#title|NPC Actions<br />
--#leftsub|@{selected|token_name}<br />
--Rfirst|@{selected|character_id};repeating_npcaction<br />
--:DisplayLoop|<br />
--?"[*R:name]" -eq NoRepeatingAttributeLoaded|Done<br />
--+Action:|[*R:name] [*R:attack_damage] [*R:attack_damagetype]<br />
--?"[*R:attack_damage2]" -eq ""|NoSecondaryDamage<br />
--+ |[*R:attack_damage2] [*R:attack_damagetype2]<br />
--:NoSecondaryDamage|<br />
--Rnext|<br />
-->DisplayLoop| <br />
--:Done|<br />
}}<br />
</pre><br />
<br />
[[File:Scriptcards repeating npcactions.png]]<br />
<br />
In the script above, we get the "first" repeating_npcaction and display information about it. We then execute "next" and repeat until we run into "NoRepeatingAttributeLoaded".<br />
<br />
See the section named [[#Repeating Section Values|Repeating Section Values]] for more information.<br />
<br />
'''''Special debugging command: dump'''''<br />
<pre><br />
--Rdump|<br />
</pre><br />
<br />
The "dump" command will list all of the attributes ScriptCards knows about for the currently loaded repeating row to the API Console Log.<br />
<br />
=== Assign Variable to Built-In Function (--~) ===<br />
<br />
ScriptCards has the ability to run a function built into the API script and return the results to a variable. Some functions return roll variables, while others return strings. See the function table below for details. The format is:<br />
<br />
--~VariableName|function;param1;param2;param3;...<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Function Name !! Parameters !! Description<br />
|-<br />
| distance || token_A_ID;token_B_ID || Calculate the Chebyshev distance in grid units between two tokens. This is the measurement scheme D&D 4E/5E use for diagonal distance measurement<br />
|-<br />
| euclideandistance || token_A_ID;token_B_ID || Calculate the Euclidean distance between two tokens. This is essentially the Pythagorean theorem in action. Returns the result in grid units.<br />
|-<br />
| euclideanpixel || token_A_ID;token_B_ID || Calculate the Euclidean distance between two tokens and returns the result is pixels instead of grid units. <br />
|-<br />
| euclideanlong || token_A_ID;token_B_ID || 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 is calculated instead of before. More accurate over long distances. <br />
|-<br />
| manhattandistance || token_A_ID;token_B_ID || Also called "taxicabdistance" (which is an acceptable function name), this measures to how-many-over, how-many-up/down distance, disallowing diagonal movement.<br />
|-<br />
| getselected || none || 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 the first selected token, VariableName2 the second, etc.<br />
|}<br />
<br />
'''''Functions with Sub Functions'''''<br />
<br />
Most ScriptCards functions are grouped into set as sub functions. The table below lists the major functions and their sub functions.<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Function Name !! Sub Function !! Parameters !! Return Type !! Description<br />
|-<br />
| array || define || arrayname;value1;value2;... || none || Creates an array called "arrayname" and adds value1, value2, etc. to the array<br />
|-<br />
| array || sort || arrayname || none || Sorts the specified array in place in ascending order<br />
|-<br />
| array || add || arrayname;value1;value2;... || none || Adds value1, value2, ... to the existing array "arrayname"<br />
|-<br />
| array || remove || arrayname;value1;value2;... || none || Removes value1, value2, ... from the existing array "arrayname". Resets the array index to 0.<br />
|-<br />
| array || replace || arrayname;currentvalue;newvalue || none || Replaces all occurrences of "currentvalue" in "arayname" with "newvalue"<br />
|-<br />
| array || setatindex || arrayname;index;newvalue || none || Replaces the array item at index "index" with "newvalue"<br />
|-<br />
| array || getindex || arrayname || stringVariable || Retrieves the current index in "arrayname" and stores it in the supplied string variable<br />
|-<br />
| array || setindex || arrayname;newindex || none || Sets the current index in array "arrayname" to "newindex"<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| array || removeat || arrayname;indexposition || none || Removes the item at index "indexposition" from "arrayname". Resets the current array index to 0.<br />
|-<br />
| array || indexof || arrayname;searchvalue || stringVariable || Searches the array "arrayname" for and item with the value of "searchvalue" and, if found, returns the index of the first matching value or "ArrayError" if not found<br />
|-<br />
| array || getlength || arrayname || stringVariable || Returns the number of items in array "arrayname"<br />
|-<br />
| array || pagetokens || arrayname;tokenid;(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. 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.)<br />
|-<br />
| 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.<br />
|-<br />
| array || stringify || arrayname || stringVariable || Returns all of the items in "arrayname" as a string separated by semicolons (;)<br />
|-<br />
| array || fromstring || arrayname || delimiter;string || Creates an array from "string", splitting "string" on "delimiter" to separate the items<br />
|-<br />
| array || statusmarkers|| arrayname;tokenid || none|| Creates an array (arrayname) of the active statusmarkers (sometimes called Token Markers) for the specified tokenid<br />
|-<br />
| math || angle || math;angle;tokenid;tokenid|| rollVariable || Calculates the angle between two tokens and returns the value in degrees<br />
|-<br />
| math || ceil || math;ceil;value || rollVariable || Rounds '''value''' up to the next integer, dropping any decimal portion of the number<br />
|-<br />
| math || clamp || math;clamp;value;lowerBound;upperBound || rollVariable || Returns '''value''', but restricted to the range of '''loweBound''' and '''upperBound'''.<br />
|-<br />
| math || floor || math;floor;value || rollVariable || Rounds '''value''' down, dropping any decimal portion of the number<br />
|-<br />
| math || max || math;max;valueA;valueB || rollVariable || Returns the larger of '''valueA''' vs '''valueB'''<br />
|-<br />
| math || min || math;min;valueA;valueB || rollVariable || Returns the smaller of '''valueA''' vs '''valueB'''<br />
|-<br />
| math || round || math;round;value || rollVariable || Rounds '''value''' to the nearest integer<br />
|-<br />
| string || length || string;length;stringValue || rollVariable || Returns the length of '''stringValue''' in characters<br />
|-<br />
| string || before || string;before;searchText;stringValue || stringVariable || Searches '''stringValue''' for '''searchText''' and returns the portion of '''stringValue''' prior to that text<br />
|-<br />
| string || after || string;after;searchText;stringValue || stringVariable || Searches '''stringValue''' for '''searchText''' and returns the portion of '''stringValue''' after that text<br />
|-<br />
| string || left || string;left;count;stringValue || stringVariable || Returns the leftmost '''count''' characters of '''stringValue'''<br />
|-<br />
| string || right || string;right;count;stringValue || stringVariable || Returns the rightmost '''count''' characters of '''stringValue'''<br />
|-<br />
| string || replace || string;replace;searchText;replaceText;stringValue || stringVariable || Replaces '''searchText''' in '''stringValue''' with '''replaceText''' and returns the resulting string<br />
|-<br />
| string || replaceall || string;replace;searchText;replaceText;stringValue || stringVariable || Replaces all intances of '''searchText''' in '''stringValue''' with '''replaceText''' and returns the resulting string '''''Requires 1.2.9+'''''<br />
|-<br />
| string || trim || string;trim;stringValue || stringVariable || Removes leading and trailing spaces from stringValue and returns the result. <br />
|-<br />
| string || substring || string;substring;start;count;stringValue || stringVariable || Returns '''count''' characters starting at '''start''' from '''stringValue'''<br />
|-<br />
| 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.<br />
|-<br />
| string || tolowercase || string;tolowercase;stringValue || stringVariable || Converts the passed string to lower case and assigns to the passed variable name. <br />
|-<br />
| string || touppercase || string || stringVariable || Converts the passed string to upper case and assigns to the passed variable name. <br />
|-<br />
| 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. <br />
|-<br />
| 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.<br />
|-<br />
| 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'''.<br />
|-<br />
| turnorder || clear || none || none || Clears all entries from the {{Turn Tracker}}/Initiative<br />
|-<br />
| turnorder || addtoken || tokenid;trackervalue || none || Adds the token represented by "tokenid" to the initiative tracker with an initiavie value of "trackervalue"<br />
|-<br />
| turnorder || replacetoken || tokenid;trackervalue || none || Replaces the token represented by "tokenid" in the initiative tracker with an initiavie value of "trackervalue". Will add the token if it doesn't exist in the tracker.<br />
|-<br />
| turnorder || removetoken || tokenid || none || Removes the token represented by "tokenid" from the initiative tracker if it exists<br />
|-<br />
| turnorder || addcustom || textlabel;trackervalue || none || Add a custom text entry to the {{Turn Tracker}}/Initiative named "textlabel" with an initiative value of "trackervalue"<br />
|-<br />
| system || date || getdatetime || stringVariable || Returns the date time in the active timezone (see settings) <br />
|-<br />
| system || date || getdate || stringVariable || Returns the date in the active timezone (see settings) <br />
|-<br />
| system || date || gettime || stringVariable || Returns the time in the active timezone (see settings)<br />
|-<br />
| system || dumpvariables || "rolls", "string", or "array" || none || Dumps all of the defined variables of the indicated type to the console log<br />
|-<br />
| system || findability || system;findability;charactername;abilityname || stringVariable || Returns the object ID of the ability on the indicated character or "AbilityNotFound"<br />
|-<br />
|}<br />
<br />
Examples:<br />
<br />
<pre><br />
--~HowFarAway|distance;@{selected|token_id};@{target|token_id}<br />
</pre><br />
<br />
Returns the distance (Chebyshev) between the selected and target tokens and stores it in "HowFarAway".<br />
<br />
<pre><br />
--SelectedDudes|getselected<br />
</pre><br />
<br />
If 5 tokens were selected, 6 variables would be created: SelectedDudesCount (with a value of 5), SelectedDudes1, SelectedDudes2, SelectedDudes3, SelectedDudes4, SelectedDudes5.<br />
<br />
=== Information Request (--i) ===<br />
<br />
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.<br />
<br />
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.<br />
<br />
After the user has clicked the button and responded to the requests, ScriptCards will resume processing the script from where it left off.<br />
<br />
Here is an example “i” line:<br />
<br />
<pre><br />
--IScriptCards needs additional information to continue;Click to select a target and provide information|t;MyNewTarget;Missile1Target||q;MyNameIs;What is your name?<br />
</pre><br />
<br />
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.<br />
<br />
Supported information request types are “t” for target token, and “q” for query.<br />
<br />
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).<br />
<br />
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:<br />
<br />
<pre><br />
q;UserName;What is your name?|Fred|Bob|Sally|Nancy<br />
</pre><br />
<br />
Would have a dropdown menu with four choices.<br />
<br />
== Inline Formatting ==<br />
<br />
Inline formatting is processed on Direct Output lines only (--+ lines) and the following inline format markup is available:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Formatting Tags !! Description<br />
|-<br />
| [b]..[/b] || Bold the text between the markers <br />
|-<br />
| [i]..[/i] || Italicize the text between the markers <br />
|-<br />
| [u]..[/u] || Underline the text between the markers <br />
|-<br />
| [s]..[/s] || Strike-Thru the text between the markers <br />
|-<br />
| [c]..[/c] || Center alignment <br />
|-<br />
| [l]..[/l] || Left alignment <br />
|-<br />
| [r]..[/r] || Right alignment <br />
|-<br />
| [j]..[/j] || Full justification alignment <br />
|-<br />
| [#xxx]..[/#] or [#xxxxxx]..[/#] || Use a 3 or 6 digit hex code to colorize the text between the markers <br />
|-<br />
| [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, <code>[img width=128 height=128]</code> )<br />
|-<br />
| [button]caption::action[/button] || Create a button with the label "caption" that performs the action defined by "action". <br />
|-<br />
| [t] || Converted to HTML table tag. Text after the "t" will be included inside the tag (width, border, etc)<br />
|-<br />
| [/t] || Converted to HTML close table tag.<br />
|-<br />
| [tr] || Converted to HTML table row tag. Text after the "tr" will be included inside the tag<br />
|-<br />
| [/tr] || Converted to HTML close table row tag.<br />
|-<br />
| [td] || Converted to HTML table cell tag. Text after the "tr" will be included inside the tag<br />
|-<br />
| [/td] || Converted to HTML close table cell tag.<br />
|}<br />
<br />
== Variables ==<br />
<br />
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. While it is possible to assign both a string and a roll variable the same name, doing so will likely result in confusion when looking at the script later, so it is not recommended.<br />
<br />
String Variables are assigned with the --& statement and are referenced using [&variableName] notation.<br />
<br />
Roll Variables are assigned with the --= statement, and the assignment value is always processed by the ScriptCards Roll Processor (resolves dice rolls, etc.)<br />
<br />
There are a handful of variables assigned automatically when a ScriptCard is executed. These are all string variables, and are:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Variable !! Value<br />
|-<br />
| SendingPlayerID || Contains the object ID of the player that sent the macro<br />
|-<br />
| SendingPlayerName || Contains the display name of the player<br />
|-<br />
| SendingPlayerColor || Contains the color code associated with the player<br />
|-<br />
| SendingPlayerSpeakingAs || The contents of the "Speaking As" dropdown window<br />
|-<br />
| SendingPlayerIsGM || Contains 1 if the player is a GM, and 0 if the player is NOT a GM<br />
|}<br />
<br />
== Arrays ==<br />
<br />
Arrays are a special type of variable, and are managed by the function (<nowiki>--~</nowiki> command). All of the array function commands follow the same pattern:<br />
<br />
<pre>--~variableName|array;subcommand;arrayname;param1;param2;param3;...</pre><br />
<br />
Not all array commands return anything to "variableName". The function table above will specify the return type of the command if any.<br />
<br />
There are a couple of different ways to create an array:<br />
<br />
The '''define''' array subcommand creates (or recreates) an array and assigns it values - one for each included parameter after the array name. For example:<br />
<br />
<pre>--~|array;define;Fruits;mango;peach;strawberry;apricot;banana;apple</pre><br />
<br />
will create an array called '''Fruits''' with 6 elements in the order listed in the command (mango, peach, etc.)<br />
<br />
You can also use two other subcommands to create arrays based on tokens:<br />
<br />
<pre>--~Count|array;pagetokens;Everybondy;@{selected|token_id}</pre><br />
<br />
and<br />
<br />
<pre>--~Count|array;selectedtokens;Selected</pre><br />
<br />
In both cases, arrays of tokens will be created, and a string variable called "Count" will be set to the number of tokens in the array. The '''pagetokens''' command returns (by default) all of the tokens on the page that contains the token passed as the parameter after the array name. You can filter the tokens that "pagetokens" includes in the array by appending an optional parameter describing the type of token you are looking for:<br />
<br />
<pre>--~Count|array;pagetokens;Everybondy;@{selected|token_id};npc</pre><br />
<br />
Will return only tokens on the page that represent characters that do not have a ''controlledby'' parameter set. The available options are "all" (default), "char", "graphic", "pc", and "npc".<br />
<br />
The '''selectedtokens''' command returns an array with all of the tokens that were selected when the script was called.<br />
<br />
You can also use an arbitrary string to create an array, specifying a delimiter with the '''fromstring''' command:<br />
<br />
<pre><br />
--&names|Fred<br />
--&names|+,Sally<br />
--&names|+,Ted<br />
--&names|+,Joyce<br />
--~|array;fromstring;,;[&names]<br />
</pre><br />
<br />
The above example builds a comma-separated string and then uses "fromstring" to create an array with 4 elements from it, specifying the comma as the delimiter.<br />
<br />
Finally, you can use the '''statusmarkers''' command to create an array with one entry for each active status marker on a specified token:<br />
<br />
<pre>--~|array;statusmarkers;Conditions;@{selected|token_id}</pre><br />
<br />
will create an array with one entry for each status active on the selected token. The array elements will be the internal name of the status (if you are using custom status marker packs, the names will be specified in the marker pack).<br />
<br />
'''Traversing Arrays'''<br />
<br />
Each array keeps track of an internal index position (starting at 0). Several commands let you manage this index:<br />
<br />
*'''getindex''' returns the current index value<br />
*'''setindex''' sets the index to the specified location in the array<br />
*'''getlength''' returns the number of elements in the array<br />
*'''indexof''' returns the index location of the specified element<br />
<br />
Other commands let you retrieve values from the array:<br />
<br />
*'''getfirst''' sets the index to 0 and returns the value at that position<br />
*'''getnext''' advances the index by 1 and returns the new current value<br />
*'''getprevious''' reduces the index by 1 and returns the new current value<br />
*'''getlast''' sets the index to the last elements in the array and returns the new current value<br />
<br />
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.<br />
<br />
'''Manipulating Array Elements'''<br />
<br />
Several array commands deal with inserting, removing, and modifying elements:<br />
<br />
*'''add''' works just like define, except that it takes an existing array and adds elements to it based on the passed parameters<br />
*'''remove''' looks for items matching each passed parameter and removes them from the indicated array if they exist<br />
*'''removeat''' allows you to specify an index location in the array and remove the element at that position<br />
*'''replace''' searches an array for a value and replaces all occurrences of it with a new value (if found)<br />
*'''sort''' sorts the elements in the array in ascending order<br />
*'''strinfigy''' returns a string variable that includes each array element separated by semicolons (;) <br />
<br />
'''Referencing Array Elements'''<br />
<br />
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.<br />
<br />
<pre><br />
!script {{<br />
--~dummy|array;pagetokens;myarray;@{selected|token_id}<br />
--~count|array;getcount;myarray<br />
--+Total:|There are [&count] graphical objects on the page<br />
--~testvar|array;getfirst;myarray<br />
--:loop|<br />
--+Value|[*[&testvar]:character_name]<br />
--~testvar|array;getnext;myarray<br />
--?[&testvar] -ne ArrayError|loop<br />
--+Loop1|Is Done!<br />
}}<br />
</pre><br />
<br />
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:<br />
<br />
<pre><br />
!script {{<br />
--~dummy|array;pagetokens;myarray;@{selected|token_id}<br />
--~count|array;getcount;myarray<br />
--+Total:|There are [&count] graphical objects on the page<br />
--%loopCounter|1;[&count]<br />
--+Value|[*[@myarray([&loopCounter])]:character_name]<br />
--%|<br />
--+Loop|Is Done!<br />
}}<br />
</pre><br />
<br />
This line : <nowiki>--+Value|[*[@myarray([&loopCounter])]:character_name]</nowiki> uses [@arrayName(index)] format (inside a [*characterid:attribute] syntax) to perform the same task as running through the loop with the index.<br />
<br />
(Note: Additional examples are on the way...)<br />
<br />
== For...Next Loops ==<br />
<br />
For...Next loops in ScriptCards are supported with the with the --% statement type. A loop is defined by starting off with:<br />
<br />
<pre><br />
--%LoopCounter|<start>;<end>;[step]<br />
</pre><br />
<br />
The start and end values are required, while the step parameter is optional. If the step is omitted, it will be assumed to be 1. A string variable named after the line tag ("LoopCounter" in the case above) will be created and will hold the current iteration value for the loop. Here is a real example:<br />
<br />
<pre><br />
--%LoopCounter|1;10;1<br />
</pre><br />
<br />
This will begin a loop identified by "LoopCounter" that will start at 1, increasing by 1 each iteration (the step) until it has completed 10 executions.<br />
<br />
The "next" statement is simply <code>--%|</code>, with no tag or parameters. This indicates to ScriptCards that it should increment the counter and go back to the beginning of the loop. Extending the example above:<br />
<br />
<pre><br />
!script {{<br />
--%LoopCounter|1;10;1<br />
--=Roll|1d20<br />
--+Loop|Counter is [&LoopCounter], roll was [$Roll]<br />
--%|<br />
}}<br />
</pre><br />
<br />
The <code>--%!|</code> sequence will break out of the loop, no matter how many iterations are remaining.<br />
<br />
The % and %! character sequences can also be used as part of a 1.2.1+ non-branching conditional to continue or break the loop:<br />
<br />
<pre><br />
--?"X[&RollInto]X" -eq "XX"|%<br />
</pre><br />
<br />
In this example, if the string variable RollInfo is empty, the loop will return to the top and continue with the next iteration, while:<br />
<br />
<pre><br />
--?"X[&RollInto]X" -eq "XX"|%!<br />
</pre><br />
<br />
Would cause the whole loop to end if the condition were true.<br />
<br />
== Referencing ==<br />
<br />
=== Roll Variables===<br />
<br />
Roll Variables can be referenced from the content portion of any line type, and from the tag portion of conditional statements. The referenced value is replaced when the line is executed.<br />
<br />
There are several modifiers that can be used to reference parts of a roll:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Modifier !! Meaning<br />
|-<br />
| No modifier || In a Direct Output Line (<nowiki>--+</nowiki>), GM Output Line (<nowiki>--*</nowiki>), or String Assignement (<nowiki>--&</nowiki>), 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<br />
|-<br />
| .Total || The end result of the roll equation. Formatting rules for "No Modifier" apply based on line type. <br />
|-<br />
| .Raw || The total value of the roll variable without any formatting, no matter what kind of line the reference is used in.<br />
|-<br />
| .Base || The cumulative result of any dice rolled in the Roll Text (Numeric modifiers are not included) <br />
|-<br />
| .Ones || The number of dice in the roll that came up as 1s <br />
|-<br />
| .Aces || The number of dice in the roll that came up as the maximum number on the die <br />
|-<br />
| .Odds || The number of dice in the roll that came up with an odd number <br />
|-<br />
| .Evens || The number of dice in the roll that came up with an even number <br />
|-<br />
| .RollText || The raw text of the roll that was use to generate the results <br />
|-<br />
| .Text || A text representation of the results of the roll, including the numbers rolled for each die <br />
|-<br />
| .tableEntryText || The text portion of the result of a table roll<br />
|-<br />
| .tableEntryImgURL || The image source portion of the result of a table roll<br />
|-<br />
| .tableEntryValue || If the tableEntryText is purely numeric, will contain the numeric value<br />
|}<br />
<br />
=== String Variables ===<br />
<br />
To reference a string variable, use the notation [&variablename]. String variables can be referenced in direct output, roll variable assignment, and string variable assignment statements.<br />
<br />
=== Character/Token Attributes ===<br />
<br />
A character or token attribute can be referenced from content portion of any type of line and is substituted when the line is executed. The general format for referencing a character attribute is [*ID:attribute]. ID can be a token ID or a character ID (these start with a dash). Additionally if you have specified a sourceToken or targetToken, you can substitute "S" or "T" for the ID (for example [*S:npc_type] will retrieve the npc_type attribute from the source token.<br />
<br />
By default, all attribute references will be pulled from the '''''character''''' object that the ID represents (either directly or by being a Token ID that represents a character).<br />
<br />
Keep in mind, that if you want to access the "max" of a character attribute (for example, the max hit points), then you cannot trust the name that your roll20 character sheet shows you when you hover your mouse over the max hit points. For example, this reference will not work: [*S:hp_max]. Instead, you need to use this reference: [*S:hp^].<br />
<br />
If your ID refers to a token, token attributes can be accessed by preceding the attribute name with "t-", for example [*S:t-aura1_radius]. Supported token attributes are:<br />
<br />
{|<br />
| t-name || t-id || t-statusmarkers || t-bar1_value<br />
|-<br />
| t-bar1_max || t-bar2_value || t-bar2_max || t-bar3_value<br />
|-<br />
| t-bar3_max || t-top || t-left || t-width<br />
|-<br />
| t-height || t-rotation || t-layer || t-aura1_radius<br />
|-<br />
| t-aura1_color || t-aura2_radius || t-aura2_color || t-aura1_square<br />
|-<br />
| t-aura2_square || t-tint_color || t-light_radius || t-light_dimradius<br />
|-<br />
| t-light_angle || t-light_losangle || t-light_multiplier || t-light_otherplayers<br />
|-<br />
| t-light_hassight || t-flipv || t-fliph || t-controlledby<br />
|-<br />
| t-_cardid || t-_pageid || t-imgsrc || t-bar1_link<br />
|-<br />
| t-bar2_link || t-bar3_link || t-represents || t-layer<br />
|-<br />
| t-isdrawing || t-name || t-gmnotes || t-showname<br />
|-<br />
| t-showplayers_name || t-showplayers_bar1 || t-showplayers_bar2 || t-showplayers_bar3<br />
|-<br />
| t-showplayers_aura1 || t-showplayers_aura2 || t-playersedit_name || t-playersedit_bar1<br />
|-<br />
| t-playersedit_bar2 || t-playersedit_bar3 || t-playersedit_aura1 || t-playersedit_aura2<br />
|-<br />
| t-lastmove || t-adv_fow_view_distance || t-has_bright_light_vision || t-has_night_vision<br />
|-<br />
| t-night_vision_distance || t-emits_bright_light || t-bright_light_distance || t-emits_low_light<br />
|-<br />
| t-low_light_distance || t-has_limit_field_of_vision || t-limit_field_of_vision_center || t-limit_field_of_vision_total<br />
|-<br />
| t-has_limit_field_of_night_vision || t-limit_field_of_night_vision_center || t-limit_field_of_night_vision_total || t-has_directional_bright_light<br />
|-<br />
| t-directional_bright_light_center || t-directional_bright_light_total || t-has_directional_dim_light || t-directional_dim_light_center<br />
|-<br />
| t-directional_dim_light_total || t-lightColor || || |<br />
|}<br />
<br />
'''''It is important to note that some attributes names on tokens have corresponding attribute names on characters, which represent different values. For example, [*T:id] returns the character ID, while [*T:t-id] returns the token ID.'''''<br />
<br />
=== Subroutine Parameters ===<br />
<br />
When using a gosub statement (-->) or a conditional marked as a gosub (prefixing the label with a > character), you can pass any number of parameters separated by semicolons (;) that the code in the subroutine can utilize.<br />
<br />
Subroutine parameters are numbered starting at 1, and are accessed by using the notation [%number%], so the first parameter is [%1%], the second is [%2%], etc.<br />
<br />
Parameter substitution happens on all line types, and happens prior to character attribute references or roll variable substitution.<br />
<br />
=== Campaign Attribute ===<br />
You can retrieve properties of the API's Campaign object with the [*C:attributename] syntax. For example, [*C:playerpageid] will retrieve the current player ribbon page from the Campaign object.<br />
<br />
=== Page Attributes ===<br />
If you have set the '''activepage''' parameter, you can retrieve page-related properties with the [*P:attributename] syntax, including the page's UDL parameters.<br />
<br />
=== Repeating Section Values ===<br />
<br />
You can reference repeating attribute data using the syntax [*R:attributename] syntax (similar to referencing standard character attributes). The currently active repeating row information will be used to retrieve attribute values. You can also retrieve the full attribute name for a repeating row attribute by using the [*R>attributename] notation. This is useful to pass to things like chatsetattr.<br />
<br />
See the section named [[#Repeating Section Access (--R)|Repeating Section Access]] for more information.<br />
<br />
=== Array Elements ===<br />
After an array has been declared, the elements can be referenced with [@arrayName(index)]. Array indices start at 0.<br />
<br />
== Deferred Resolution for Meta Scripts ==<br />
<br />
As of 1.2.9, ScriptCards supports a deferral character for use when calling another API script with via the --@ statement, to defer processing of meta script references so they get processed prior to the sub-API call insted of prior to ScriptCards execution. To defer this processing for meta script (SelectManager, Fetch) by inserting a deferral character into the meta call. For example, if I want to have ScriptCards call TokenMod as if the token for "Quej Gr'stra" (yes, I let Roll20 name my test NPCs) I could use something like this:<br />
<br />
--@token-mod|{^& select Quej Gr'stra} _on showname<br />
<br />
The "^" in between { and & will prevent SelectManager from seeing the call when the ScriptCard script is processed, but the --@ statement will remove the deferral character so the command that will be sent by ScriptCards is:<br />
<br />
!token-mod {& select Quej Gr'stra} --on showname<br />
<br />
With the deferral character removed, SelectManager will see the {& select ...} and do its magic.<br />
<br />
While the default deferral character is "^", the deferral character is a setting that can be changed:<br />
<br />
--#deferralcharacter|%<br />
<br />
Will make % the deferral character for future --@ statements in the running script.<br />
<br />
There are currently three supported Meta script structures: {^&...} for SelectManager, @^(...) and *^(...) for fetch, where the ^ in the structures here represents the placement of the deferral character.<br />
<br />
== Arrays ==<br />
<br />
Arrays are a new data type introduced in version 1.1.12 of ScriptCards, and are manipulated with associated function (--~) commands.<br />
<br />
* Arrays are a lists of strings. Items in an array cannot contain the semi-colon (;) character, as that is used to separate parameters in the function code that deals with arrays.<br />
* Arrays are accessed via the --~ script command. In some cases, the value of the tag (variable name) for array commands is not used, and can be a dummy value or simply omitted. I have omitted them in the statements below.<br />
* All commands that DO return a value return string values, even if the content is numeric.<br />
* If a command returns a value and there is some sort of reason that it isn't an array value, you will get "ArrayError" in the return value. This can happen if you reach the end of an array while stepping through it, for example, so checking for "ArrayError" can serve as the end condition for a loop.<br />
* Each array keeps track of its current index, allowing you to step forward and backwards through arrays.<br />
* Any number of arrays can be defined.<br />
* Unlike string variables and roll variables, array variables cannot (currently) be referenced directly. It is necessary to use the function (--~) syntax to manipulate arrays and get values from them as strings for use in other parts of your script.<br />
<br />
<br />
== Reentrant Scripts ==<br />
<br />
Reentrant scripts allow you to create buttons in your script code that will re-execute the script at a given label within the code. If you set the reentrant setting (--#reentrant|somevalue) to a non-zero value, your setting and variable information will be preserved between executions. Reentrant script can be used to present menus or choices and then continue acting.<br />
<br />
Reentrant buttons are created with the [rbutton]Caption::ReentryLabel;Parameter[/rbutton] construct. The caption will be displayed on the generated button. ReentryLabel is the name of a label in your script that the button will jump to when clicked, and Parameter will be passed in as a string value called "reentryval".<br />
<br />
Example:<br />
<pre><br />
!script {{<br />
--#reentrant|testing<br />
--=Roll|1d20<br />
--+Roll|[$Roll]<br />
--&String|That was a [$Roll.Raw]!<br />
--~x|array;define;MyArray;Apple;Banana;Orange<br />
--+Try it|[rbutton]Hello!::EXEC_PC_SPELL;9[/rbutton]<br />
--X|<br />
<br />
--:EXEC_PC_SPELL|<br />
--+ReentryVal|[&reentryval]<br />
--+The value of Roll is|[$Roll]<br />
--+Value of String|[&String]<br />
--+Array|[@MyArray(0)]<br />
--X|<br />
}}<br />
</pre><br />
<br />
This script sets up some variables and then displays a button labeled "Hello!". If the user clicks the button, the script will be re-entered starting at the "EXEC_PC_SPELL", which will display the content of the variables from the original execution.<br />
<br />
'''''Note: This section needs to be expanded upon'''''<br />
<br />
== Procedure Libraries ==<br />
<br />
You can now create handouts in your game in Roll 20 with the name format "ScriptCards Library NAME", where name is a name you assign to the library. Library names are case sensitive. It is my hope that the more proficient ScriptCards scripters out there will provide procedure libraries (or procedures that can be included in libraries) for others to use to make their scripting life easier. Be they specific to a game system, or to a type of activity, I think a robust set of libraries that GMs could use to enhance their scripting capabilities would be very valuable to the community. Should such things begin to emerge, I’ll create a portion of the ScriptCards Wiki page to house them.<br />
<br />
To include one or more libraries in a script, use the +++libname+++ directive (does not need a -- line associated with it). Multiple library names can be specified by separating them with semicolons (i.e., +++General;dnd5elib;Colorize+++ would include three libraries (General, dnd5elib, and Colorize).<br />
<br />
Included libraries are separated from the main script code by the automatic inclusion of "--X|" before the first library is appended to the script, and all libraries are loaded at the end of the script before script processing takes place.<br />
<br />
Procedures and labels in libraries can be used just as if they were included in the body of your script. Note that this DOES mean that you could, technically, jump into a library with a direct branch (--^) or direct branch conditional, but I recommend using libraries to store reusable procedures.<br />
The Notes section of the library handout stores the library code, and is written just like any other ScriptCards code except:<br />
<br />
* They cannot use roll queries (?{Some Prompt:}) to get information from the user at execution time.<br />
* They cannot use @{} notation to access character and token information.<br />
<br />
Both of these limitation stem from the fact that Procedure Libraries are not processed by the chat server, which is what handles these items.<br />
<br />
Here is an example of handling damage modifications (resistance, vulnerability, and immunity) in D&D 5E with a library:<br />
<br />
<pre><br />
!script {{<br />
+++dnd5elib+++<br />
--#|Damage Modifiers Test<br />
--#targettoken|@{target|token_id}<br />
-->Lib5E_CheckDamageModifiers|ResistType;fire<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] fire damage<br />
<br />
-->Lib5E_CheckDamageModifiers|ResistType;cold<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] cold damage<br />
<br />
-->Lib5E_CheckDamageModifiers|ResistType;poison<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] poison damage<br />
<br />
-->Lib5E_CheckDamageModifiers|ResistType;acid<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] acid damage<br />
<br />
--X|<br />
}}<br />
</pre><br />
<br />
Library content (In a handout called “ScriptCards Library dnd5elib” NOTE: Paste into Notepad first and then paste into the handout in Roll20 to avoid bringing over HTML formatting from the web site):<br />
<br />
<pre><br />
--/|ScriptCards Library: dnd5elib version 0.0.1<br />
--/|Provides various utility procedures for D&D 5E games<br />
<br />
--/|Lib5E_CheckDamageModifiers handle damage resistance, vulnerability, and immunity. <br />
--/|Pass a string variable to be filled with a string to be appended to a dice roll and the damage type <br />
<br />
--:Lib5E_CheckDamageModifiers|damageVariableName;damageType<br />
--&[%1%]|<br />
--?"[*T:npc_vulnerabilities]" -inc "[%2%]"|>_Lib5E_IsVulnerable;[%1%]<br />
--?"[*T:npc_resistances]" -inc "[%2%]"|>_Lib5E_IsResistant;[%1%]<br />
--?"[*T:npc_immunities]" -inc "[%2%]"|>_Lib5E_IsImmune;[%1%]<br />
--<|<br />
<br />
--:_Lib5E_IsVulnerable| --&[%1%]| * 2 [Vulnerable] --<|<br />
--:_Lib5E_IsResistant| --&[%1%]| \ 2 [Resistant] --<|<br />
--:_Lib5E_IsImmune| --&[%1%]| * 0 [Immune] --<|<br />
</pre><br />
<br />
The idea is that the functions in the library create a string that can be appended to a roll to modify the output based on resistances, so you pass Lib5E_CheckDamageModifiers the name of the string variable you want to use and the damage type. The variable (ResistType in this case) will include either nothing, “* 2 [Vulnerable]”, “\ 2 [Resistant]”, or “* 0 [Immune]” which can be included in a roll assignment (--=) to modify the damage as appropriate. The order here might be important if an NPC is misconfigured to be both resistant and immune to the same damage type. Since immune is an absolute, having it last ensures that it will override resistant or vulnerable. A creature that is both vulnerable and resistant (again, misconfigured) will come back as resistant since that condition is checked after vulnerable.<br />
Some notes: I prefix my library labels with either “Lib5E_” or “_Lib5E_” as a clarity convention. This isn’t strictly necessary but you should be aware that if two libraries (or if your script and a library) define the same label, the last label defined will win. Since libraries are appended to the end of the script in the order you include them in the +++libname+++ directive, you can somewhat control this, but it is probably best to avoid re-declaring labels. <br />
<br />
In my case, items beginning with “Lib5E_” are intended to be called by scripts, while items beginning with “_Lib5E_” are intended to be used as subroutines by the “public” procedures. Of course, there is no reason you couldn’t call them directly.<br />
<br />
You might also note that I’ve included some library information in comment lines (--/|) at the top of the library. These are ignored by ScriptCards, and are a good way to convey requirements, parameters, usage information, etc.<br />
<br />
== Example Libraries ==<br />
<br />
=== dnd5elib ===<br />
<br />
[https://github.com/kjaegers/ScriptCards Download the dnd5elib Library from the ScriptCards GitHub]<br />
<br />
The '''dnd5elib''' library provides a collection of utility procedures that help simplify dealing with the D&D 5E Official Sheet. Some of the procedures in this library require '''chatsetattr''' to be installed in your game. This is a growing library, and currently only has a handful of routines. They are:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Procedure Name !! Notes<br />
|-<br />
| style="white-space:nowrap" | Lib5E_CheckDamageModifiers || This procedure can be used to evaluate vulnerabilities, resistances, and invulnerabilities on an NPC. After setting the --#target| parameters, pass the Lib5E_CheckDamageModifiers procedure a variable name (no reference information) and a damage type (i.e., fire, cold, bludgeoning, etc.) and a string variable with the name passed in as the first parameter will be created that contains text that can be included in a roll line (--=) in order to modify the roll as appropriate. For example, '''-->Lib5E_CheckDamageModifiers|ResistType;fire''' will check the current target character's attributes for "fire" and will either return an empty string (no references), "* 0 [Immune]" if the creature is immune, "\ 2 [Resistant]" if the creature is resistant, or "* 2 [Vulnerable]" if the creature is vulnerable to fire damage.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_DeductSpellSlot || Pass in a character_id and a slot level, and the script will expend one spell slot of that level, capping the value at 0 slots remaining. For Example '''<nowiki>-->Lib5E_DeductSpellSlot|@{selected|character_id};1</nowiki>''' to deduct a first level spell slot from the selected character.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_FindResource || Used to locate a resource value on a character. Pass in a character_id, a resource name, and two variable names. The procedure will check both repeating and non-repeating resources looking for a resource whose name matches what was passed in and return three variables. The first will be a string variable named for the 3rd parameter and contains the attribute name of the resource's "name" field. The second will be a string variable named after parameter 4 and contains the resource's value field attribute name, and the third variable is a Roll Variable, also named after the 4th parameter that contains the current resource value. Example: '''<nowiki>-->Lib5E_FindResource|@{selected|character_id};Crossbow bolts;ResName;ResValue</nowiki>''' will find "Crossbow bolts" as a resource on the character and return [&ResName] which is the name of the resource attribute, [&ResValue] which is the '''name of the attribute that stores the value''' and [$ResValue] which is the current numeric value of the resource.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Global_Attack_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Attack Modifiers (repeating_tohitmod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Bless" for 1d4 active and "Being Cool" for +2 active, I will get a return string " + 1d4 [Bless] + 2 [Being Cool]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Save_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Save Modifiers (repeating_savemod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Bless" for 1d4 active and "Being Cool" for +2 active, I will get a return string " + 1d4 [Bless] + 2 [Being Cool]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Skill_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Skill Modifiers (repeating_skillmod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Guidance" for 1d4 active and "Being Cool" for +2 active, I will get a return string " + 1d4 [Guidance] + 2 [Being Cool]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_AC_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Save Modifiers (repeating_savemod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Shield of Faith" with a value of 2 active, I will get a return string " + 2 [Shield of Faith]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Damage_Modifiers || Pass a character ID and TWO string variable to set the return value. The first string will be for normal damage, and the second will be the additional damage on a crit. This procedure will look through the Global Damage Modifiers (repeating_damagemod_*) for rows that are active (checked on the character sheet) and return two strings with the dice rolls and descriptions for them (for example, if I have "Sneak Attack" with a value of 1d6 normal and 1d6 critical damage active, I will get a return string " + 1d6 [Sneak Attack]" and another string of " + 1d6 [Sneak Attack CRIT]" that can be used in a dice rolls.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_DivineSmiteDice || Used to calculate the number of dice to be rolled for a paladin's Divine Smite. Pass a target token id, a spell slot level, and a string variable to be set to the dice roll amount based on the NPC_TYPE attribute of the target token. The returned variable will contain a dice roll (like "3d8" that can be used in a --= line)<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Character_Summary || Pass a character ID to outputs a mini character sheet, including clickable buttons for attacks, actions, legendary actions, etc. Will automatically detect a PC vs NPC and output the appropriate sections.<br />
|}<br />
<br />
Due to formatting issues with the Wiki, the library code has been moved to a [https://gist.github.com/kjaegers/52f6049ddd257f0a1288aca4bbde13c5 GITHUB GIT]. Please view the GIST in raw mode and copy the text and paste it into a handout called "ScriptCards Library dnd5elib" in your Roll20 Game.<br />
<br />
== What to Know if you are Coming from PowerCards ==<br />
<br />
''Note: This section is a work in progress.''<br />
<br />
While ScriptCards and PowerCard have very similar output goals, their internals and use are quite different. The table below summarizes some of the major differences between the scripts.<br />
<br />
::{| class="wikitable"<br />
|-<br />
! PowerCards !! ScriptCards <br />
|-<br />
| With a handful of exceptions, all lines in a PowerCard macro are intended to produce a line of output on the final card. || With ScriptCards, ONLY the <code>--+</code> and <code>--*</code> statement types produces output <br />
|-<br />
| PowerCards lines begin with two dashes (<code>--</code>) followed by a unique tag name for the line, followed by a vertical bar and the content for the line. || ScriptCards lines begin with two dashes (<code>--</code>) followed by a '''statement type identifier''', which is a single character that identifies the type of line to the interpreter. This is followed by a tag (frequently optional), a vertical bar, and the parameters for the statement being executed.<br />
|-<br />
| PowerCard macros are always processed top to bottom. Lines can be hidden so they don't output anything, but there is no looping or branching (--SkipTo looks like a branch, but it just hides all of the lines until the referenced label. || ScriptCards scripts support true branching, including direct branching (<code>--^</code>) and procedure branching (<code>--></code>) and (<code>--<</code>). Procedures support parameters and a call stack so procedures can be nested to call other procedures.<br />
|-<br />
| All lines in a PowerCards macro need to have unique tags because PowerCards builds the card as a single JavaScript object using the tag names to store what will be displayed. This is why repeated tag names always result in the last one being shown. || ScriptCards tags do not need to be unique, and in the case of many line types are optional.<br />
|-<br />
| PowerCards conditionals result in either showing or hiding the line they are on. || ScriptCards conditionals '''''only''''' support branching as the result of the comparison. This branching can be direct (a GOTO) or procedural (a GOSUB) '''''NOTE: As of version 1.2.0, ScriptCards also supports roll/string variable assignment as a result of conditional evaluation'''''<br />
|-<br />
| PowerCards relies on the Roll20 [[Quantum Roll]] server and inline rolls for all dice functions || ScriptCards includes its own dice roll parser, and '''''does not support''''' inline rolls.<br />
|-<br />
| PowerCards RollIDs (often mistaken for variables) are assigned by analyzing the results of an inline roll, and cannot be referenced in other rolls, so you can't roll a <code>1d4</code> and then roll a <code>1d20</code> and add the <code>1d4</code> result because all of the rolls happen on the chat server before PowerCards gets the macro text. || ScriptCards supports two types of variables: Roll Variables and String Variables. Because ScriptCards uses its own roll parser and is not dependent upon the chat server, rolls and their results can be used in other rolls, math functions, output, etc.<br />
|}<br />
<br />
== Example Scripts ==<br />
<br />
Below are some sample scripts that utilize the various statement types in ScriptCards:<br />
<br />
=== Divine Smite ===<br />
<br />
This script will prompt the user for a spell slot level to expend on a divine smite. It will check the target's npc_type to see if it is an Undead or Fiend, which adds an additional d8 to the smite roll.<br />
<br />
[[File:ScriptCards Divine Smite.png|Divine Smite Script Output]]<br />
<br />
<pre><br />
!scriptcard {{<br />
--#title|Divine Smite<br />
--=DiceCount|?{Spell Slot Level?|1|2|3|4|5|6|7|8|9} + 1<br />
--=IsFiendOrUndead|0<br />
--?"@{target|npc_type}" -inc fiend|>IsBoosted<br />
--?"@{target|npc_type}" -inc undead|>IsBoosted<br />
--=TotalDice|[$DiceCount] + [$IsFiendOrUndead]<br />
--=SmiteRoll|[$TotalDice]d8<br />
--#emoteText|@{selected|token_name} smites @{target|token_name}<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
--+Smite|deals [$SmiteRoll] radiant damage.<br />
--X|<br />
<br />
--:IsBoosted|<br />
--=IsFiendOrUndead|1<br />
--<|<br />
}}<br />
</pre><br />
<br />
==== How It Works ====<br />
<br />
The first line sets the "title" card parameter to "Divine Smite".<br />
<br />
Line 2 Shows a query to the user asking for the spell slot level, adds one and stores the value in the "DiceCount" Roll Variable. The query/dropdown is generated by the chat server prior to the script being executed.<br />
<br />
Line 3 defaults the "IsFiendOrUndead" Roll Variable to 0.<br />
<br />
Lines 4 and 5 compare the target's "npc_type" attribute (passed by the chat server as text) to see if they include either "undead" or "fiend". If true, the IsBoosted subroutine will be called. No parameters are passed to this subroutine.<br />
<br />
Line 6 sets the "TotalDice" variable to the base (DiceCount) number plus the IsFiendOrUndead number, which will be a 0 or a 1.<br />
<br />
Line 7 calculates "SmiteRoll" by rolling a number of d8 equal to the "TotalDice" value.<br />
<br />
Lines 8-10 set the parameters for the emote, which appears above the card content. By setting the sourceToken and the targetToken, their icons will appear in the emote surrounding the text describing the action.<br />
<br />
Line 11 is the only line that actually produces output on the card. It results in "Smite deals # radiant damage".<br />
<br />
Line 12 ends the script execution, preventing the script from continuing and running the subroutines out of context.<br />
<br />
Lines 14-16 are the IsBoosted subroutine, starting with the :IsBoosted label. The IsFiendOrUndead variable is set to 1, and a return from subroutine is executed.<br />
<br />
=== Magic Missile ===<br />
<br />
This script demonstrates using a loop and calling a subroutine to fire a number of missiles determine by the spell slot level used to cast the spell.<br />
<br />
[[File:ScriptCards_MagicMissile_Fixed.png|Magic Missile Script Output]]<br />
<br />
<pre><br />
!scriptcard {{ <br />
--#title|Magic Missile<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
--=MissileCount|?{Spell Slot Level?|1|2|3|4|5|6|7|8|9} + 2<br />
--=DisplayCount|1<br />
--=MissileDamage|0<br />
--#leftsub|Slot level ?{Spell Slot Level?}<br />
--#rightsub|Ranged Attack<br />
--#emoteText|Fred uses a level ?{Spell Slot Level?} spell slot to fire [$MissileCount.Total] missiles of magical force!<br />
--:MissileLoop|<br />
-->FireMissile|<br />
--=DisplayCount|[$DisplayCount] + 1<br />
--?[$DisplayCount] -le [$MissileCount]|MissileLoop<br />
--+Total|Total damage is [$MissileDamage]<br />
--X|<br />
<br />
--:FireMissile|<br />
--=ThisMissile|1d4 + 1<br />
--=MissileDamage|[$MissileDamage] + [$ThisMissile]<br />
--+Missile|[$DisplayCount.Total] Hits for [$ThisMissile] [b]force[/b] damage<br />
--<|<br />
}}<br />
</pre><br />
<br />
==== How It Works ====<br />
<br />
Lines 1-3 set the card title, the source token and the target token. Setting these tokens causes their icons/avatars to appear in the Emote section of the card.<br />
<br />
Line 4 asks the user what spell slot level they wish to use to cast magic missile. The number of missiles fired is equal to 2 plus the spell level, and this is stored in the MissileCount variable.<br />
<br />
Line 5 stores a 1 in the DisplayCount variable. This will be used to control the loop to determine the number of missiles fired and the missile number when displaying damage rolls.<br />
<br />
Line 6 initializes MissileDamage to 0<br />
<br />
Line 7 sets the left subtitle to the text "Slot Level #", where # is the spell slot level being used.<br />
<br />
Line 8 sets the right subtitle to the text "Ranged Attack".<br />
<br />
Line 9 sets the emoteText parameter with a description of the action, including the slot level and number of missiles fired.<br />
<br />
Line 10 is a label for the missile firing loop<br />
<br />
Line 11 Calls the "FireMissile" subroutine<br />
<br />
Line 12 increases the DisplayCount variable by 1<br />
<br />
Line 13 Checks to see if there are still missles to fire (DisplayCount <= MissileCount) and if so branches to MissileLoop<br />
<br />
Line 14 Displays the total damage dealt by the spell.<br />
<br />
Line 15 stops execution of the script to prevent out of context execution of the subroutine.<br />
<br />
Lines 76-21 are the FireMissile subroutine, beginning with the FireMissile label. The 1d4+1 is rolled and assigned to "ThisMissile". The result is added to the existing MissileDamage total, and a line for the current missile is displayed with the missile number and the damage for the missile.<br />
<br />
=== Longsword Attack ===<br />
<br />
This script demonstrates a standard 5E D&D melee weapon attack, including detection of misses, fumbles, hits, and critical hits. If installed, alterbars is used to decrement the target's BAR3 value by the damage dealt.<br />
<br />
[[File:ScriptCards Longsword.png|Longsword Script Output]]<br />
<br />
<pre><br />
!scriptcard {{<br />
--#title|Longsword<br />
--#leftsub|Melee Attack<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
--#emoteText|@{selected|token_name} attacks @{target|token_name}<br />
--=TargetAC|@{target|npc_ac}<br />
--?[$TargetAC.Total] -gt 0|DoneWithAC<br />
--=TargetAC|@{target|ac}<br />
--:DoneWithAC|<br />
--=AttackRoll|1d20 + @{selected|strength_mod} [STR] + @{selected|pb} [PROF]<br />
--+Attack|@{selected|token_name} rolls [$AttackRoll] vs AC [$TargetAC].<br />
--?[$AttackRoll.Base] -eq 20|Crit<br />
--?[$AttackRoll.Base] -eq 1|Fumble<br />
--?[$AttackRoll.Total] -ge [$TargetAC.Total]|Hit<br />
--+Miss|The attack missed.<br />
--^Final|<br />
<br />
--:Fumble|<br />
--+Fumble!|The attack went horribly wrong.<br />
--^Final|<br />
<br />
--:Hit|<br />
--=Damage|1d8 + @{selected|strength_mod} [STR]<br />
--+Hit!|The attack hit @{target|token_name} for [$Damage] slashing damage.<br />
--@alter|_target|@{target|token_id} _bar|3 _amount|-[$Damage]<br />
--^Final|<br />
<br />
--:Crit|<br />
--=Damage|1d8 + @{selected|strength_mod} [STR] + 1d8 [CRIT]<br />
--+Critical Hit!|The attack hit @{target|token_name} for [$Damage] slashing damage.<br />
--@alter|_target|@{target|token_id} _bar|3 _amount|-[$Damage]<br />
<br />
--:Final|<br />
}}<br />
</pre><br />
<br />
==== How it Works ====<br />
<br />
In lines 1-5, we set the title, subtitle, and emote text along with the tokens for the emote area.<br />
<br />
Lines 6-9 allow us to determine the AC of the target. On the 5E Roll20 sheet, NPCs armor class is stored in "npc_ac", while PCs armor class is in "ac". First we grab npc_ac and if it is zero, we check AC.<br />
<br />
Line 10 rolls the attack roll, rolling 1d20 and adding the attacker's strength modifier and proficiency bonus<br />
<br />
Line 11 displays the result of the attack roll on the card<br />
<br />
Lines 12-14 determine what kind of result the attack had. If the .Base value of the roll was 20, we branch to "Crit". If it was 1, we branch to "Fumble". If the .Total value of the roll was greater than or equal to the AC that was determined in Lines 6-9, we branch to Hit.<br />
<br />
Assuming we didn't branc anywhere, the result of the attack was a miss, so we display that on line 15 and then branch to "Final"<br />
<br />
This is followed by three branch segments, :Fumble, :Hit, and :Crit. A fumble displays a text message and branches to :Final.<br />
<br />
On a hit or a crit, we roll Damage (adding additional damage dice on a crit). We display a "Hit!" or "Critical Hit!" message and then make an API call to AlterBars, passing it the token id, bar we want to modify (3 in this case), and the amount we want to modify by the Damage value.<br />
<br />
=== Party Health Status ===<br />
<br />
This example calculates the current Hit Points remaining and HP percentage for each character and creates a color-coded display with the current party status.<br />
<br />
[[File:ScriptCards Party Health.png]]<br />
<br />
<pre><br />
!scriptcard {{<br />
--#title|Party Status<br />
--#titleCardBackground|#33CC33<br />
--#oddrowbackground|#bfee90<br />
--#evenrowbackground|#90eebf<br />
-->HealthCheck|@{Quej Grastra|character_id}<br />
-->HealthCheck|@{Brim Cheuto|character_id}<br />
-->HealthCheck|@{Odug Ututees|character_id}<br />
--X|End of card Execution<br />
<br />
--:HealthCheck|<br />
--=HealthPerc|[*[%1%]:hp] / [*[%1%]:hp^] * 100 \ 1<br />
--=HealthColor|000000<br />
--?[$HealthPerc.Total] -gt 50|HealthSkip<br />
--=HealthColor|FF0000<br />
--:HealthSkip|<br />
--+[*[%1%]:character_name]|has [#[$HealthColor.RollText]][*[%1%]:hp] of [*[%1%]:hp^][/#] HP [R]([$HealthPerc.Total]%)[/R]<br />
--<|End of HealthCheck<br />
}}<br />
</pre><br />
<br />
==== How it Works ====<br />
<br />
Lines 1-4, we set the card title, and set the title background and row background colors to shades of green.<br />
<br />
Lines 5-7 make gosub calls the the "HealthCheck" subroutine, passing in the character ID of each of the named characters (these are the names of the characters in my test game)<br />
<br />
Line 8 terminates the script execution.<br />
<br />
The remaining lines of the script are the HealthCheck subroutine, which works like this:<br />
<br />
Line 10 is the subroutine label (:HealthCheck)<br />
<br />
Line 11 uses the character id passed as a parameter and combines it with character attribute lookup *(...) to retrieve the value of "hp" and "hp<nowiki>^</nowiki>" for the character. The <nowiki>^</nowiki> character is used to specify that we want the MAX value for this attribute for the second call. We divide these two numbers and multiple by 100 to get a percentage. Finally, we use integer division by 1 to round the percentage and drop the decimals. The end result gets stored in the HealthPerc roll variable.<br />
<br />
Line 12 defaults to color of the health text to black<br />
<br />
Line 13 check to see if the health percentage is greater than 50. If so, it branches to HealthSkip, preventing the script from executing line 13.<br />
<br />
Line 14 sets the color of the health text to red<br />
<br />
Line 15 is the label that will be branched to from Line 13 to skip the red coloring<br />
<br />
Line 16 again uses character attribute substitution and the passed parameter value to output a display line containing the character name, the colorized health total, and the percentage value. The percentage is right-justified.<br />
<br />
Line 17 returns from the HealthCheck subroutine.<br />
<br />
=== Expanded Magic Missile Script ===<br />
<br />
This is the expanded and enhanced version of the Magic Missile script covered in {{yt|watch?v=u50xvNzS9Zk | this video}}. It includes visual and audio effects, checking and deducting spell slots, and applying damage using either Token-Mod or Alterbars.<br />
<br />
<pre><br />
!scriptcard {{ <br />
--#title|Magic Missile<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
<br />
-->GetAndCheckSlotInformation|<br />
<br />
--=MissileCount|[$SlotLevel] + 2<br />
--=DisplayCount|1<br />
--=MissileDamage|0<br />
--#leftsub|Slot level [$SlotLevel]<br />
--#rightsub|Ranged Attack<br />
--#emoteText|@{selected|character_name} uses a level [$SlotLevel.Total] spell slot to fire [$MissileCount.Total] missiles of magical force!<br />
<br />
--:MissileLoop|<br />
-->FireMissile|<br />
--=DisplayCount|[$DisplayCount] + 1<br />
--?[$DisplayCount] -le [$MissileCount]|MissileLoop<br />
--+Total|Total damage is [$MissileDamage]<br />
-->DeductSpellSlot|<br />
--#rightsub|Level [$SlotLevel] Left: [$SlotsRemaining] <br />
-->PlayEffects|none;burst-smoke;beam-magic;spell_01<br />
-->ApplyDamageTokenmod|@{target|token_id};3;-[$MissileDamage]<br />
-->ApplyDamageAlterbars|@{target|token_id};3;-[$MissileDamage]<br />
--X|<br />
<br />
--:FireMissile|<br />
--=ThisMissile|1d4 + 1<br />
--=MissileDamage|[$MissileDamage] + [$ThisMissile]<br />
--+Missile|[$DisplayCount.Total] Hits for [$ThisMissile] [b]force[/b] damage<br />
--<|<br />
<br />
--:GetAndCheckSlotInformation|<br />
--=SlotLevel|?{Spell Slot Level?|1|2|3|4|5|6|7|8|9}<br />
--=SlotsTotal|[*S:lvl[$SlotLevel]_slots_total]<br />
--=SlotsExpended|[*S:lvl[$SlotLevel]_slots_expended]<br />
--?[$SlotsExpended.Total] -ge [$SlotsTotal.Total]|NoSlotsLeft<br />
--<|<br />
<br />
--:NoSlotsLeft|<br />
--+|[*S:character_name] has no level [$SlotLevel.Total] spell slots available.<br />
--X|<br />
<br />
--:DeductSpellSlot|<br />
--=SlotsExpended|[$SlotsExpended] + 1<br />
--@setattr|_charid [*S:character_id] _lvl[$SlotLevel]_slots_expended|[$SlotsExpended] _silent<br />
--=SlotsRemaining|[$SlotsTotal] - [$SlotsExpended]<br />
--<|<br />
<br />
--:PlayEffects|Parameters are : source effect; target effect; line effect; sound effect<br />
--vtoken|@{selected|token_id} [%1%]<br />
--vtoken|@{target|token_id} [%2%]<br />
--vbetweentokens|@{selected|token_id} @{target|token_id} [%3%]<br />
--@roll20AM|_audio,play,nomenu|[%4%]<br />
--<|<br />
<br />
--:ApplyDamageTokenmod|Parameters are tokenid;bar#;amount<br />
--@token-mod|_ignore-selected _ids [%1%] _set bar[%2%]_value|[%3%]<br />
--<|<br />
<br />
--:ApplyDamageAlterbars|<br />
--@alter|_target|[%1%] _bar|[%2%] _amount|[%3%]<br />
--<|<br />
}}<br />
</pre><br />
<br />
[[Category:Featured articles]]</div>5004103https://wiki.roll20.net/Script:ScriptCardsScript:ScriptCards2021-10-01T10:57:42Z<p>5004103: /* Repeating Section Values */</p>
<hr />
<div>{{revdate}}<br />
== Introduction ==<br />
'''ScriptCards''' provides a script interpreter that can be used to create powerful macros that display the results of player/NPC actions, or display other information in a pleasing visual format in your game's chat window. The scripting language contains variables (both dice-roll (enhanced numerics) and strings) as well, conditionals, branching, subroutines with parameters, and a set of built-in functions to simplify working with Roll20 information.<br />
{{script overview<br />
|name=ScriptCards<br />
|author={{user profile|2365448|Kurt J.}}<br />
|code=<br />
|version=1.4.0e<br />
|lastmodified=2021-09-24}}<br />
ScriptCards is not game-system specific, and can be used with any system/sheet. Near the end of this Wiki there is a section set aside for libraries that can implement system-specific tasks, with the hope that enthusiasts playing particular systems will create and share utility functions that can be utilized by the wider community.<br />
<br />
The default display style for ScriptCards output is similar to the format used to document player and NPC abilities in Dungeons and Dragons 4th Edition, but does not have any system ties to D&D4E.<br />
<br />
Current OneClick Version : 1.4.0e<br />
<br />
Current Development Version : 1.4.4<br />
<br />
'''''<big>Critically Important: ScriptCards does not use/parse inline rolls. ScriptCards includes its own built-in dice roll parser to allow for the use of variables inside dice rolls. As of version 1.2.3, ScriptCards will now take inline rolls and substitute the total result value in statement strings, meaning that you can utilize inline rolls but ScriptCards will only see the result of the roll, and not parse the roll components itself.</big>'''''<br />
<br />
* {{fpl|9752053/ ScriptCards thread}}<br />
** {{fpl|10000297/ Scritpcard API Working and Sharing}}<br />
* https://github.com/kjaegers/ScriptCards/tree/main/ScriptCards_API - GitHub repository for source before the one-click version is updated.<br />
* {{yt.be|hyR7Jnq4mQM ScriptCards Intro}} 45min, Jan 2021<br />
* {{yt.be|u50xvNzS9Zk ScriptCards Magic Missile Deep Dive}} 39min, Feb 2021<br />
<br />
<br />
__TOC__<br />
=== Is ScriptCards Related to [[PowerCards]]? ===<br />
<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
Check the '''[[#What to Know if you are Coming from PowerCards|What to Know if you are Coming from PowerCards]]'''-section for a comparison table between the two scripts.<br />
<br />
== What is a ScriptCard Script ==<br />
<br />
A ScriptCard Script is text written into the chat window (either typed directly, pasted, or run via a macro) that will produce a card of information in the [[text Chat|chat window]]. A ScriptCard Script is composed of an [[API]] command: <code><nowiki>!scriptcard {{ }}</nowiki></code> enclosing any number of lines that determine the output that will be added to the card. At it simplest, the following macro:<br />
<br />
<pre>!scriptcard {{ }}</pre><br />
<br />
Will produce just a title card that displays “ScriptCards” as the name:<br />
<br />
[[File:Scriptcard blank.png]]<br />
<br />
Of course, this is just the simplest type of macro and isn’t very useful. In order to produce useful output, we need to include lines between the <code><nowiki>{{</nowiki></code> and <code><nowiki>}}</nowiki></code> that direct the API script as to what it should do.<br />
<br />
== Structure of a ScriptCard Line ==<br />
<br />
All ScriptCard lines begin with two dashes, followed by an ''statement identifier character'' that lets ScriptCards what type of line it is. There are several of these, and they are detailed in the next section. After the line type identifier, a Tag name 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.<br />
<br />
Following the Tag is a vertical bar, and then the content of the line itself. Again, each type of line might interpret this content differently.<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Identifier !! Statement Type !! Tag !! Content !! Notes<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--/</nowiki> || Comment || unused || unused || The <code>--/</code> 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--#</nowiki> || 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").<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--+</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--=</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--&</nowiki> || Assign String 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. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--@</nowiki> || 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 (i.e., [[TokenMod|!token-mod]], or [[ChatSetAttr|!setattr]], etc.)<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--:</nowiki> || 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<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--^</nowiki> || Branch To || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--></nowiki> || Call Procedure || 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<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--<</nowiki> || 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.<br />
|- <br />
| style="white-space:nowrap" | <nowiki>--?</nowiki> || Conditional Branch || Condition to be evaluated || True Branch Label<nowiki>|</nowiki>False Branch Label || The condition will be evaluated and execution will jump to one of the two indicated branches (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 included a semicolon separated list of parameters. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--s</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--l</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--v</nowiki> || 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+'''''<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--e</nowiki> || Echo to Chat || Name to send chat command as || Chat message to send || Variable substitution takes place on the tag and content.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--R</nowiki> || Retrieve Repeating Section Row information || "find", "first", or "next" || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--~</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--c</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--i</nowiki> || Information Request || User Prompt;Button Caption || InfoType;VariableName;ParameterText || See full documentation below.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--d</nowiki> || 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. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--%</nowiki> || 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. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--*</nowiki> || 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.<br />
|}<br />
<br />
== ScriptCard Statement Type Details ==<br />
The sections below detail the individual statement types supported by ScriptCards<br />
<br />
=== Comment (--/) ===<br />
<br />
A --/ statement is ignored by the ScriptCards parser. You can use this type of statement to add comments and informational text to your script. <br />
<br />
Example:<br />
<pre><br />
!script {{<br />
--/|Script Name : Fireball<br />
--/|Purpose : Allow the player to cast a fireball and blow stuff up!<br />
.<br />
.<br />
.<br />
}}<br />
</pre><br />
<br />
=== Set Parameter (--#) ===<br />
<br />
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.<br />
<br />
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.<br />
<br />
'''''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.'''''<br />
<br />
Examples:<br />
<pre><br />
--#title|Magic Missile<br />
--#leftsub|Level 1 Spell<br />
--#rightsub|Force Damage<br />
</pre><br />
<br />
The three examples above set the “title”, “leftsub”, and “rightsub” values for the card to the content value for the line. <br />
<br />
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.<br />
Settings Lines do not produce output lines on the card.<br />
<br />
The following settings are available (note that parameter names are ''not'' case sensitive):<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Name !! Effect/Use !! Default Value !! Type<br />
|-<br />
| 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<br />
|-<br />
| allowplaintextinrolls || If set to a non-zero value, plain character text in rolls will be copied to the roll text || 0 || Per-Line<br />
|-<br />
| bodyFontFace || Name of the font used in the card rows || Helvetica || Global<br />
|-<br />
| bodyFontSize || Size of the text in the card rows || 14px || Global<br />
|-<br />
| bodybackgroundimage || Specify an image (content for a CSS background-image tag) for the body area || none || Global<br />
|-<br />
| buttonBackground || Background color for buttons created with [button][/button] || #1C6EA4 || Per-Line<br />
|-<br />
| buttonBorderColor || Border (outline) color for buttons created with [button][/button] || #999999 || Per-Line<br />
|-<br />
| buttonFontFace || Font Family specifier for captions on buttons created with [button][/button] || Tahoma || Per-Line<br />
|-<br />
| buttonFontSize|| Text size for captions on buttons created with [button][/button] || x-small || Per-Line<br />
|-<br />
| buttonTextColor|| Text color of labels on buttons created with [button][/button] || #FFFFFF || Per-Line<br />
|-<br />
| 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<br />
|-<br />
| deferralcharacter || Changes the meta script deferral sequence to the specified value || ^ || Per-Line<br />
|-<br />
| diceFontColor|| Color of the dice created with the [d4] [d6], etc. formatting markers || #1C6EA4 || Per-Line<br />
|-<br />
| dicefontsize || Size of the dice created with the [d4] [d6], etc. formatting markers || 3.0em || Per-Line<br />
|-<br />
| 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<br />
|-<br />
| disablerollprocessing || If set to a non-zero value, --= lines will not process dice rolls strings || 0 || Per-Line<br />
|-<br />
| emoteBackground || Background color of the emote area || #f5f5ba || Global<br />
|-<br />
| emoteFont || Name of the font used in emote area (above the title of the output card) || Georgia || Global<br />
|-<br />
| emoteFontColor || Color of the font in the emote area || None (Empty) || Global<br />
|-<br />
| emoteFontSize || Size of the font used in the emote area || 14px || Global<br />
|-<br />
| emoteFontWeight || Font weight for the font in the emote area || bold|| Global<br />
|-<br />
| emoteState || If set to anything other than "visible", the emote portion of the card will not be displayed || visible || Global<br />
|-<br />
| emoteText || Text to display in the emote portion of the card || None (Empty) || Global<br />
|-<br />
| emotefont || Name of the font used in the emote text area || font-family: Georgia, serif; font-weight: bold; || Global<br />
|-<br />
| evenRowBackground || Hex code for the background color for even rows || #eeeeee || Per-Line<br />
|-<br />
| evenRowFontColor || Hex code for the text color for even rows || #000000 || Per-Line<br />
|-<br />
| evenrowbackgroundimage || Specify an image (content for a CSS background-image tag) for the even card rows || none || Per-Line<br />
|-<br />
| executionlimit || Maximum number of script lines the interpreter will try to execute. This prevents "infinite loop" sandbox crashes || 40000 || Global<br />
|-<br />
| hideCard || If set to any non-default value, the entire card output will be suppressed || 0 || Global<br />
|-<br />
| 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<br />
|-<br />
| 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<br />
|-<br />
| lineheight || Vertical size of each line on the output card || normal || Per-Line<br />
|-<br />
| nominmaxhighlight || If set to anything other than "0", rolls will not display crit/fumble/mixed highlight colors. || 0 || Per-Line<br />
|-<br />
| norollhighlight || If set to anything other than "0", rolls will not be formatted (plain numbers) but will still get a tooltip with details ('''''v1.3.6b+''''') || 0 || Per-Line<br />
|-<br />
| oddRowBackground || Hex code for the background color for even rows || #d0e4f5 || Per-Line <br />
|-<br />
| oddRowFontColor || Hex code for the text color for odd rows || #000000 || Per-Line<br />
|-<br />
| oddrowbackgroundimage || Specify an image (content for a CSS background-image tag) for the odd crd rows || none || Per-Line<br />
|-<br />
| reentrant || Used to name a script for rentrant button use || 0 || Global<br />
|-<br />
| 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)0 || Global<br />
|-<br />
| rollhilightlineheight || Determines the height of the hilight box placed around roll results ('''''1.4.2+''''') || 1.0em || Per-Line<br />
|-<br />
| roundUp || If set to a non-default value, integer division will round up instead of down || 0 || Per-Line<br />
|-<br />
| showfromfornonwhispers || If set to a non-zero value, will include the sender on cards that aren't whispered || 0 || Global<br />
|-<br />
| 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<br />
|-<br />
| subtitleFontColor || Color of the text in the subtitle areas || #FFFFFF || Global<br />
|-<br />
| subtitleFontFace || Name of the font used on the subtitle sections || Tahoma || Global<br />
|-<br />
| subtitleFontSize || Size of the subtitle font || 13px || Global<br />
|-<br />
| subtitleSeperator || The character(s) that will be placed between leftsub and rightsub || <nowiki>&#x2666</nowiki>; || Global<br />
|-<br />
| tableBorderRadius || CSS specifier for how rounded the borders of the output card are. Use "0px;" for square borders || 6px; || Global<br />
|-<br />
| tableShadow || CSS specifier for the drop shadow under the output card || 5px 3px 3px 0px #aaa; || Global<br />
|-<br />
| tablebgcolor || Background color of the whole card. '''''Normally not visible''''' || #EEEEEE || Global<br />
|-<br />
| tableborder || Color of the border that surrounds the whole card || 2px solid #000000; || Global<br />
|-<br />
| 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<br />
|-<br />
| timezone || IANA Specifier for the local time zone, used in system/date functions || merica/New_York || Per-Line<br />
|-<br />
| title || Text displayed in the title area of the card || ScriptCards || Global<br />
|-<br />
| titleCardBackground || A hex color code representing the background color of the title area. || #1c6ea4 || Global<br />
|-<br />
| titleFontColor || Color of the text on the card title || #FFFFFF || Global<br />
|-<br />
| titleFontFace || Name of the font used on the title area || Contrail One || Global<br />
|-<br />
| titleFontLineHeight || Line spacing on the title area || 1.2em || Global<br />
|-<br />
| titleFontSize || Size of the title font || 1.2em || Global<br />
|-<br />
| titlecardbackgroundimage || Specify an image (content for a CSS background-image tag) for the title card area || none || Global<br />
|-<br />
| titlecardbottomborder || Border CSS specifier for the bottom of the title card area || 2px solid #444444; || Global<br />
|-<br />
| titlecardgradient || If set to non-zero value, will place a vertical gradient on the title card area || 0 || Global<br />
|-<br />
| usehollowdice || If set to a non-zero value, the hollow/outline versions of the dice fonts will be used || 0 || Per-Line<br />
|-<br />
| whisper|| Comma separated list of who to whisper the output to. Use "gm" for [[GM|GMs]] and "self" for the sender || none || Global|}<br />
|}<br />
<br />
''Setting Lines do not produce output lines on the card''<br />
<br />
=== Direct Output (--+) ===<br />
<br />
A direct output line display 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.<br />
<br />
Examples of Direct Output lines:<br />
<pre><br />
--+Hello|World<br />
--+Attack|The monster rolls [$Attack] to hit!<br />
--+Damage|@{target|token_name} is hit for [$Damage] [#3333AA][b]frost[/b][/#] damage.<br />
</pre><br />
<br />
Direct Output lines support inline formatting, roll variable replacement, character attribute references, and procedure variables.<br />
<br />
=== GM Output (--*) ===<br />
<br />
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. <br />
<br />
Example:<br />
<pre><br />
--+PlayerLine|This line is shown on the public card<br />
--*GMLine|This line will only be shown to GMs, on a separate card.<br />
</pre><br />
<br />
=== Roll Variable Assignment (--=) ===<br />
<br />
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.<br />
<br />
'''''All components of a roll equation should be separated with spaces.'''''<br />
<br />
Examples:<br />
<pre><br />
--=MissileDamage|1d4 + 1<br />
--=Attack|1d20 + @{selected|strength_mod} [STR] + @{selected|pb} [PROF]<br />
</pre><br />
<br />
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. Text enclosed in square brackets ([]) is considered "flavor text" and will be added to the result text but does not impact the roll result.<br />
<br />
The following dice formats are supported:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Format Pattern !! Example !! Description<br />
|-<br />
| XdY || 3d8 || Simple format. Roll a Y-sided die X times<br />
|-<br />
| XdYkhZ || 2d20kh1 || Roll Y-sided die X times and keep the highest Z number of dice<br />
|-<br />
| XdYklZ || 4d6kl3 || Roll Y-sided die X times and keep the lowest Z number of dice <br />
|-<br />
| XdY>Z || 5d6>3 || Roll Y-sided die X times and count a 1 for each roll greater than Z <br />
|-<br />
| XdY<Z || 5d6<3 || Roll Y-sided die X times and count a 1 for each roll less than Z <br />
|}<br />
<br />
'''''Note: The dice formulae below are supported in the development version of ScriptCards and will be merged with the table above when activated on OneClick'''''<br />
::{| class="wikitable"<br />
|-<br />
! Format Pattern !! Example !! Description<br />
|-<br />
| 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<br />
|-<br />
| 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<br />
|-<br />
| 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)<br />
|-<br />
| 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<br />
|}<br />
<br />
The following operators are supported in a roll equation:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Operator !! Operation<br />
|-<br />
| + || Addition <br />
|-<br />
| - || Subtraction <br />
|-<br />
| * || Multiplication <br />
|-<br />
| / || Division <br />
|-<br />
| \ || Integer Division (Rounds down) <br />
|-<br />
| % || Modulo (Remainder of Divison)<br />
|}<br />
<br />
Roll Variables can be accessed at any time after they have been created by using the [$VariableName] format, with the following optional modifiers:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Modifier !! Meaning<br />
|-<br />
| No modifier || In a Direct Output Line (<nowiki>--+</nowiki>) 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<br />
|-<br />
| .Total || The end result of the roll equation as an unformatted number <br />
|-<br />
| .Base || The cumulative result of any dice rolled in the Roll Text (Numeric modifiers are not included) <br />
|-<br />
| .Ones || The number of dice in the roll that came up as 1s <br />
|-<br />
| .Aces || The number of dice in the roll that came up as the maximum number on the die <br />
|-<br />
| .Odds || The number of dice in the roll that came up with an odd number <br />
|-<br />
| .Evens || The number of dice in the roll that came up with an even number <br />
|-<br />
| .RollText || The raw text of the roll that was use to generate the results <br />
|-<br />
| .Text || A text representation of the results of the roll, including the numbers rolled for each die <br />
|-<br />
| .tableEntryText || The text portion of the result of a table roll<br />
|-<br />
| .tableEntryImgURL || The image source portion of the result of a table roll<br />
|-<br />
| .tableEntryValue || Numeric value of tableEntryText (via parseInt). If a non-numeric value, will be 0<br />
|-<br />
| .Raw || The total numeric result without any formatting, even if placed somewhere formatting would normally be done. <br />
|}<br />
<br />
Examples:<br />
<pre><br />
--+Total Damage|[$MissileDamage.Total] (roll was 1d4+1)<br />
--+Base Damage|[$MissileDamage.Base] (without the +1)<br />
--=Attack|1d20 + @{selected|strength_mod} [STR] + @{selected|pb} [PROF] + [$BlessBonus] [Bless]<br />
</pre><br />
<br />
In this case, 1d4 will be rolled and stored in “BlessBonus”, which can then be used in the Attack line.<br />
<br />
'''''Mathematical Functions in Roll Expressions '''''<br />
<br />
The ScriptCards roll parser works from left to right, always maintaining a current value and applying whatever comes next to the total. The following in-line functions to the roll parser. These are:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Expression !! Meaning<br />
|-<br />
| {ABS} || Absolute Value<br />
|-<br />
| {CEIL} || Ceiling value (round up to the next whole number)<br />
|-<br />
| {FLOOR} || Floor value (round down to the next whole number)<br />
|-<br />
| {ROUND} || Round value (round up if the decimal portion is greater than 0.5, otherwise round down)<br />
|-<br />
| {NEGATE} || Multiply the value by negative one.<br />
|-<br />
| {SQRT} || Take the square root of the running value. ('''''1.4.1+''''')<br />
|-<br />
| {SQUARE} || Square the running value. ('''''1.4.2+''''')<br />
|-<br />
| {CUBEROOT} || Take the cube root of the running value. ('''''1.4.2+''''')<br />
|-<br />
| {CUBE} || Cube the running value. ('''''1.4.2+''''')<br />
|-<br />
| {SIN} || Return the SIN of running value. ('''''1.4.2+''''')<br />
|-<br />
| {COS} || Return the COS of running value. ('''''1.4.2+''''')<br />
|-<br />
| {TAN} || Return the TAN of running value. ('''''1.4.2+''''')<br />
|-<br />
| {ASIN} || Return the ASIN of running value. ('''''1.4.2+''''')<br />
|-<br />
| {ACOS} || Return the ACOS of running value. ('''''1.4.2+''''')<br />
|-<br />
| {ATAN} || Return the ATAN of running value. ('''''1.4.2+''''')<br />
|}<br />
<br />
<br />
'''''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 <nowiki>[[ ]]</nowiki> 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.<br />
<br />
'''''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.<br />
<br />
'''Rolling on Rollable Tables'''<br />
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.<br />
<br />
''Roll Variable Lines do not produce output lines on the card.''<br />
<br />
=== String Variable Assignment (--&) ===<br />
<br />
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:<br />
<br />
<pre><br />
--&MyText|Hello<br />
</pre><br />
<br />
Here, we assign the text "Hello" to the string variable named MyText. You can also append text to a string variable by prefixing the content with a + sign:<br />
<br />
<pre><br />
--&MyText|+ World<br />
</pre><br />
<br />
If run after the statement above, MyText will now contain "Hello World".<br />
<br />
String variables can be referenced using the syntax [&variablename]<br />
<br />
=== Call API (--@) ===<br />
<br />
ScriptCards can use a Call API instruction to execute other API commands. The Tag contains the API 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 API command is executed.<br />
<br />
Examples:<br />
<pre><br />
--@eh|list<br />
--@alter|_target|@{target|token_id} _bar|3 _amount|-[$Damage]<br />
</pre><br />
<br />
In the first example above, the command <code>!eh list</code> will be executed, calling [[EncounterHelper]]. In the second, {{fpl|1216260/ AlterBars}} is called to modify a token's Bar 3 value.<br />
<br />
'''''Note:''''' When ScriptCards (or any API script) runs other API 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).<br />
<br />
See [[API:Script Index]] for more options.<br />
<br />
=== Branch Label (--:) ===<br />
<br />
A branch label defines a line in your code that can be reached by one of the branching instructions (<nowiki>--^</nowiki>, <nowiki>--></nowiki>, or <nowiki>--?</nowiki>). The Tag serves as the label name, and must be unique on the card.<br />
<br />
The vertical bar (|) separator must be present, but the content portion of the line is unused and can be treated as a comment.<br />
<br />
Examples:<br />
<pre><br />
--:MyLoop|<br />
--:CriticalHit|Will jump here if we roll a critical hit!<br />
</pre><br />
<br />
''A Branch Label line does not produce an output line on the card.''<br />
<br />
=== Branch (--^) === <br />
<br />
A Branch line 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.<br />
<br />
Examples:<br />
<pre><br />
--^MyLoop|Jumps to MyLoop<br />
--^SkipCrit|We didn't crit, so skip the Crit code<br />
</pre><br />
<br />
''A Branch line does not produce an output line on the card.''<br />
<br />
=== Call Procedure (-->) ===<br />
<br />
Similar to a branch, a Call Procedure (sometimes knows 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 (<nowiki>--<</nowiki>) 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 (;).<br />
<br />
Examples:<br />
<pre><br />
-->FixFormat|#3333FF;#999999<br />
</pre><br />
<br />
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%].<br />
<br />
=== Return (--<) ===<br />
<br />
A return instruction marks the end of a Gosub procedure. 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.<br />
<br />
Examples:<br />
<pre><br />
--<|<br />
--<|End of MySub<br />
</pre><br />
<br />
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.<br />
<br />
=== Conditional Statement (--?) ===<br />
<br />
A conditional statement contains some equation in the Tag that will be evaluated. '''''If any part of the comparison can/does contain a space, it needs to be surrounded by double quotes'''''<br />
<br />
Based on the true/false result of the evaluation, one of two execution paths will be taken. These execution paths are detailed in the content section of the statement. The "if true" path is specified first (directly after the vertical bar), and the "if false" path is specified after it, also separated by a vertical bar.<br />
<br />
Example:<br />
<pre><br />
--?[$AttackRoll.Total] -ge [$TargetAC]|Hit|Miss<br />
</pre><br />
<br />
'''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.'''<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Branch Format !! Meaning<br />
|-<br />
| Label || If just a label is specified, execution will branch to that label when the comparison is matched.<br />
|-<br />
| >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 <br />
|-<br />
| =VariableName || The roll variable "VariableName" will be assigned the value following a semicolon (ex: --?1 -eq 1|=Roll;1d20)<br />
|-<br />
| &VariableName || The string variable "VariableName" will be assigned the value following a semicolon (ex: --?1 -eq 1|&Result;Hit|&Result;Miss)<br />
|-<br />
| % or %! || The current for...next loop will perform the "next" action (%) or will break out (%!) <br />
|-<br />
| [ || Code block (see below)<br />
|}<br />
<br />
Examples:<br />
<pre><br />
--?[$AttackRoll.Base] -eq 20|CriticalHit<br />
--?[$AttackRoll.Base] -eq 1|>Fumble;@{selected|dexterity_mod}<br />
--?"@{target|npc_type}" -inc "undead"|&MonsterType;Undead|&MonsterType;Not Undead<br />
--?[$Attack.Total] >= [$ArmorClass]|>Hit|>Miss<br />
</pre><br />
<br />
In the first example, if the Base value of AttackRoll is a 20 (natural 20 on the die) execution will branch to the CriticalHit label.<br />
<br />
In the second example, 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%].<br />
<br />
The third example looks for the word "undead" in the npc_type attribute of the targeted character. If it exists in the text, the MonsterType string variable will be set to "Undead", otherwise it will be set to "Not Undead". <br />
<br />
The final example would call 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.<br />
<br />
''Text that does/may contain a space should be enclosed in double quotes.''<br />
<br />
The following comparison operators are available:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Comparator !! Meaning<br />
|-<br />
| -eq || Equal To <br />
|-<br />
| -eqi || Case insensitive Equal To <br />
|-<br />
| -ne || Not Equal To <br />
|-<br />
| -nei || Case insensitive Not Equal To <br />
|-<br />
| -gt || Greater Than <br />
|-<br />
| -ge || Greater Than or Equal To <br />
|-<br />
| -lt || Less Than <br />
|-<br />
| -le || Less Than or Equal To <br />
|-<br />
| -inc || Includes (text strings). <br />
|-<br />
| -ninc || Does Not Include (text strings). <br />
|}<br />
<br />
Multi-part conditionals are supported with -and and -or as separators. For example:<br />
<br />
<pre><br />
--?[$Attack.Total] -ge @{target|npc_ac} -and [$Attack.Base] -ne 20|HitButNotCrit<br />
</pre><br />
<br />
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):<br />
<br />
true AND false OR true<br />
<br />
Will be evaluated as true. The first two (true and false) will be false, but then false OR true will be true.<br />
<br />
Conversely:<br />
<br />
true or false and false<br />
<br />
Will be false, because the first true and false will evaluate to true, and then true and false will be false.<br />
<br />
'''CODE BLOCKS'''<br />
<br />
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.<br />
<br />
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:<br />
<br />
<pre><br />
!script {{<br />
--=Roll|1d2<br />
--+Roll|[$Roll]<br />
--?[$Roll.Total] -eq 2|[<br />
--&Value|Yep!<br />
--+|We are inside the TRUE portion of the block<br />
--]|[<br />
--&Value|Nope<br />
--+|We are inside the FALSE portion of the block<br />
--]|<br />
--+After|the blocks!<br />
--+Value|[&Value]<br />
}}<br />
</pre><br />
<br />
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 --]|. <br />
<br />
At this time, blocks cannot be nested, and can only be created as part of a conditional (--[ is not a valid statement type)<br />
<br />
''A conditional statement does not produce a line of output on the card.''<br />
<br />
=== Case Statement (--c) ===<br />
<br />
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 (:). Each match condition includes a branch label that will be used if the test value matches the item. 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:<br />
<br />
<pre><br />
!script {{<br />
--#title|Case Statement Testing<br />
--=Roll|1d4<br />
--C[$Roll.Total]|1:>One;[$Roll]|2:>Two;[$Roll]|3:>Three;[$Roll]|4:>Four;[$Roll]<br />
--X|<br />
<br />
--:One| --+Value|was One ([%1%]) --<|<br />
--:Two| --+Value|was Two ([%1%]) --<|<br />
--:Three| --+Value|was Three ([%1%]) --<|<br />
--:Four| --+Value|was Four ([%1%]) --<|<br />
}}<br />
</pre><br />
<br />
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 variable as a parameter.<br />
<br />
=== Save and Load (--s and --l) ===<br />
<br />
This statement pair is used to either store (--s) or load (--l) data from persistent storage. Items stored in persistent storage remain between card rolls and between Roll20 sessions. There are two types of data that can be stored: settings and roll variables. <br />
<br />
Examples:<br />
<br />
<pre><br />
--Ssettings|GreenStyle<br />
--Srollvariables|FirstCardVars<br />
</pre><br />
<br />
In this case, the tag for the statement determines what type of item is being saved (settings or rollvariables). When saving settings, all non-default settings are written to the named setting storage value. When Roll Variables are saved, all variables that currently exist will be saved to the named storage value.<br />
<br />
Loading stored items simply requires the same command with the --l statement type:<br />
<br />
<pre><br />
--Lsettings|GreenStyle<br />
--Lrollvariables|FirstCardVars<br />
</pre><br />
<br />
When loading settings, all stored settings will be applied to the current card settings. You can override settings by changing them after the load.<br />
<br />
When loading roll variables, the saved variables will be added to (or overwrite if they have the same name) any variables on the current card. This means it is safe to create roll variables before the load statement.<br />
<br />
'''Practical Uses'''<br />
The major intended use of persistent storage is for storing card formats for use in later scripts. For example, the following script:<br />
<br />
<pre><br />
!scriptcard {{<br />
--#titlecardbackground|#22CC22<br />
--#oddrowbackground|#cceecc<br />
--#evenrowbackground|#99ee99<br />
--Ssettings|@{selected|token_name}<br />
}}<br />
</pre><br />
<br />
Would save the titlecardbackground, oddrowbackground, and evenrowbackground settings to a saved list named after the selected token's name. When creating cards for that token to run later, you could include the line:<br />
<br />
<pre><br />
--Lsettings|@{selected|token_name}<br />
</pre><br />
<br />
To load all of the settings at once. By creating these setting sets for each character, you can specify a different color scheme for each character that can then be used in cards with a single formatting line.<br />
<br />
There is a supplemental ! command added to support saved settings:<br />
<br />
<pre><br />
!sc-liststoredsettings<br />
</pre><br />
<br />
Will produce a list of all stored setting names, with buttons to list the setting values stored in each group and a button to delete groups as needed.<br />
<br />
=== Visual Effects (--v) ===<br />
<br />
The --v statement can be used to create visual effects on the tabletop. The tag portion of the statement can be either "token" or "betweentokens". The content portion of the statement contains the required parameters for the effect generation, separated by spaces. If the effect is "none", no effect will be played. If any other value that doesn't match a Roll20 effect name will result in a burst-fire effect.<br />
<br />
For "token" effects, the parameters are the token id for the token the effect happens on, followed by the effect specifier.<br />
<br />
Example:<br />
<pre><br />
--vtoken|@{selected|token_id} burst-fire<br />
</pre><br />
<br />
For "betweentoken" effects, the parameters are the source token id, the target token id, and the effect specifier.<br />
<br />
Example:<br />
<pre><br />
--vbetweentokens|@{selected|token_id} @{target|token_id} beam-magic<br />
</pre><br />
<br />
'''''Version 1.2.8+'''''<br />
<br />
An additional effect specifier, "point" is available in 1.2.8+. This specifier allows you to create a visual effect at a designated X/Y pixel coordinate. Future updates will add custom-vfx support to this option. The parameters are the X and Y coordinates and the effect descriptor. As of version 1.2.9, you can also use custom effect specifiers with Point effects:<br />
<br />
<pre><br />
--vpoint|150 200 burst-fire<br />
</pre><br />
<br />
=== Echo to Chat (--e) ===<br />
<br />
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.<br />
<br />
Example:<br />
<pre><br />
--eThe Ghost|/em hovers around @{selected|character_name}... BOO!<br />
</pre><br />
<br />
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).<br />
<br />
'''''Whispering'''''<br />
<br />
You can use the echo statement to send a whisper, but there's a trick to it. If you execute this code here:<br />
<br />
<pre><br />
--eThe Ghost|/w ExamplePlayerName Boo.<br />
</pre><br />
<br />
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.<br />
<br />
So, in conclusion, it's best to use something like this when you're sending a whisper:<br />
<br />
<pre><br />
!script {{<br />
--#hidecard|1<br />
--&sender|The Ghost<br />
--&receiver|ExamplePlayerName<br />
--&message|Boo.<br />
--e[&sender]|/w [&receiver] [&message]<br />
--eScriptCards|/w gm **Whispered from [&sender] to [&receiver]:** [&message] <br />
}}<br />
</pre><br />
<br />
This will ensure that the message appears in your chat feed as well.<br />
<br />
=== Repeating Section Access (--R) ===<br />
<br />
ScriptCards (as of v0.0.13) supports accessing repeating section rows on a character sheet (for example: the attacks, the items, and the repeating resources) with the --R statement type. <br />
<br />
There are three basic commands you can use with --R, and they are specified by the tag used:<br />
<br />
'''''The "find" tag'''''<br />
<br />
An Rfind statement is used to search through a repeating field. Here is the general form of such a statement.<br />
<br />
<pre><br />
--Rfind|characterid;EntryName;SectionPrefix;SearchField<br />
</pre><br />
<br />
This is the most direct way to access a repeating section row. Supplying the character ID, followed by what you are looking for (Greatsword, for example), followed by the character sheet's section prefix (repeating_attack), followed by the field to check what you are searching for (atkname) will load the matching section (if found) into the script parsers memory. For example:<br />
<br />
<pre><br />
--Rfind|@{selected|character_id};Greatsword;repeating_attack;atkname<br />
</pre><br />
<br />
Will look at the character's "repeating_attack" section for an entry with an atkname value equal to "Greatsword". Similarly:<br />
<br />
<pre><br />
--Rfind|@{selected|character_id};Bite;repeating_npcaction;name<br />
</pre><br />
<br />
Will look for a "Bite" action on an NPC's action list.<br />
<br />
'''''The "first" tag'''''<br />
<br />
<pre><br />
--Rfirst|characterid;section prefix<br />
</pre><br />
<br />
This form of the --R command will look at all of the entries in the specified repeating section and load the first one into memory:<br />
<br />
<pre><br />
--Rfirst|@{selected|character_id};repeating_attack<br />
</pre><br />
<br />
Would load the character's first "repeating_attack" row into memory.<br />
<br />
'''''The "next" tag'''''<br />
<br />
<pre><br />
--Rnext|<br />
</pre><br />
<br />
No parameters are required for --Rnext, which loads the next entry in the list that was obtained with "first" into memory.<br />
<br />
'''''The section prefixes for the 5E by roll20 character sheet'''''<br />
<br />
Can somebody please add a list of them here?<br />
<br />
'''''Additional information'''''<br />
<br />
However a row is obtained, it will be parsed to replace any attribute references (ie, @{level}) with the corresponding character attribute.<br />
<br />
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".<br />
<br />
You can reference repeating attribute data using the syntax [*R:attributename] syntax (similar to referencing standard character attributes).<br />
<br />
Here are some examples:<br />
<br />
Display the details of the "Greatsword" PC attack:<br />
<br />
<pre><br />
!script {{<br />
--Rfind|@{selected|character_id};Greatsword;repeating_attack;atkname<br />
--+Attack Name|[*R:atkname]<br />
--+Base Damage|[*R:dmgbase]<br />
}}<br />
</pre><br />
<br />
[[File:Scriptcards repeating greatsword.png|Repeating Greatsword Attack]]<br />
<br />
List all of the actions an NPC can take (just actions, not legendary, etc.)<br />
<br />
<pre><br />
!script {{<br />
--#title|NPC Actions<br />
--#leftsub|@{selected|token_name}<br />
--Rfirst|@{selected|character_id};repeating_npcaction<br />
--:DisplayLoop|<br />
--?"[*R:name]" -eq NoRepeatingAttributeLoaded|Done<br />
--+Action:|[*R:name] [*R:attack_damage] [*R:attack_damagetype]<br />
--?"[*R:attack_damage2]" -eq ""|NoSecondaryDamage<br />
--+ |[*R:attack_damage2] [*R:attack_damagetype2]<br />
--:NoSecondaryDamage|<br />
--Rnext|<br />
-->DisplayLoop| <br />
--:Done|<br />
}}<br />
</pre><br />
<br />
[[File:Scriptcards repeating npcactions.png]]<br />
<br />
In the script above, we get the "first" repeating_npcaction and display information about it. We then execute "next" and repeat until we run into "NoRepeatingAttributeLoaded".<br />
<br />
'''''Special debugging command: dump'''''<br />
<pre><br />
--Rdump|<br />
</pre><br />
<br />
The "dump" command will list all of the attributes ScriptCards knows about for the currently loaded repeating row to the API Console Log.<br />
<br />
=== Assign Variable to Built-In Function (--~) ===<br />
<br />
ScriptCards has the ability to run a function built into the API script and return the results to a variable. Some functions return roll variables, while others return strings. See the function table below for details. The format is:<br />
<br />
--~VariableName|function;param1;param2;param3;...<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Function Name !! Parameters !! Description<br />
|-<br />
| distance || token_A_ID;token_B_ID || Calculate the Chebyshev distance in grid units between two tokens. This is the measurement scheme D&D 4E/5E use for diagonal distance measurement<br />
|-<br />
| euclideandistance || token_A_ID;token_B_ID || Calculate the Euclidean distance between two tokens. This is essentially the Pythagorean theorem in action. Returns the result in grid units.<br />
|-<br />
| euclideanpixel || token_A_ID;token_B_ID || Calculate the Euclidean distance between two tokens and returns the result is pixels instead of grid units. <br />
|-<br />
| euclideanlong || token_A_ID;token_B_ID || 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 is calculated instead of before. More accurate over long distances. <br />
|-<br />
| manhattandistance || token_A_ID;token_B_ID || Also called "taxicabdistance" (which is an acceptable function name), this measures to how-many-over, how-many-up/down distance, disallowing diagonal movement.<br />
|-<br />
| getselected || none || 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 the first selected token, VariableName2 the second, etc.<br />
|}<br />
<br />
'''''Functions with Sub Functions'''''<br />
<br />
Most ScriptCards functions are grouped into set as sub functions. The table below lists the major functions and their sub functions.<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Function Name !! Sub Function !! Parameters !! Return Type !! Description<br />
|-<br />
| array || define || arrayname;value1;value2;... || none || Creates an array called "arrayname" and adds value1, value2, etc. to the array<br />
|-<br />
| array || sort || arrayname || none || Sorts the specified array in place in ascending order<br />
|-<br />
| array || add || arrayname;value1;value2;... || none || Adds value1, value2, ... to the existing array "arrayname"<br />
|-<br />
| array || remove || arrayname;value1;value2;... || none || Removes value1, value2, ... from the existing array "arrayname". Resets the array index to 0.<br />
|-<br />
| array || replace || arrayname;currentvalue;newvalue || none || Replaces all occurrences of "currentvalue" in "arayname" with "newvalue"<br />
|-<br />
| array || setatindex || arrayname;index;newvalue || none || Replaces the array item at index "index" with "newvalue"<br />
|-<br />
| array || getindex || arrayname || stringVariable || Retrieves the current index in "arrayname" and stores it in the supplied string variable<br />
|-<br />
| array || setindex || arrayname;newindex || none || Sets the current index in array "arrayname" to "newindex"<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| array || removeat || arrayname;indexposition || none || Removes the item at index "indexposition" from "arrayname". Resets the current array index to 0.<br />
|-<br />
| array || indexof || arrayname;searchvalue || stringVariable || Searches the array "arrayname" for and item with the value of "searchvalue" and, if found, returns the index of the first matching value or "ArrayError" if not found<br />
|-<br />
| array || getlength || arrayname || stringVariable || Returns the number of items in array "arrayname"<br />
|-<br />
| array || pagetokens || arrayname;tokenid;(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. 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.)<br />
|-<br />
| 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.<br />
|-<br />
| array || stringify || arrayname || stringVariable || Returns all of the items in "arrayname" as a string separated by semicolons (;)<br />
|-<br />
| array || fromstring || arrayname || delimiter;string || Creates an array from "string", splitting "string" on "delimiter" to separate the items<br />
|-<br />
| array || statusmarkers|| arrayname;tokenid || none|| Creates an array (arrayname) of the active statusmarkers (sometimes called Token Markers) for the specified tokenid<br />
|-<br />
| math || angle || math;angle;tokenid;tokenid|| rollVariable || Calculates the angle between two tokens and returns the value in degrees<br />
|-<br />
| math || ceil || math;ceil;value || rollVariable || Rounds '''value''' up to the next integer, dropping any decimal portion of the number<br />
|-<br />
| math || clamp || math;clamp;value;lowerBound;upperBound || rollVariable || Returns '''value''', but restricted to the range of '''loweBound''' and '''upperBound'''.<br />
|-<br />
| math || floor || math;floor;value || rollVariable || Rounds '''value''' down, dropping any decimal portion of the number<br />
|-<br />
| math || max || math;max;valueA;valueB || rollVariable || Returns the larger of '''valueA''' vs '''valueB'''<br />
|-<br />
| math || min || math;min;valueA;valueB || rollVariable || Returns the smaller of '''valueA''' vs '''valueB'''<br />
|-<br />
| math || round || math;round;value || rollVariable || Rounds '''value''' to the nearest integer<br />
|-<br />
| string || length || string;length;stringValue || rollVariable || Returns the length of '''stringValue''' in characters<br />
|-<br />
| string || before || string;before;searchText;stringValue || stringVariable || Searches '''stringValue''' for '''searchText''' and returns the portion of '''stringValue''' prior to that text<br />
|-<br />
| string || after || string;after;searchText;stringValue || stringVariable || Searches '''stringValue''' for '''searchText''' and returns the portion of '''stringValue''' after that text<br />
|-<br />
| string || left || string;left;count;stringValue || stringVariable || Returns the leftmost '''count''' characters of '''stringValue'''<br />
|-<br />
| string || right || string;right;count;stringValue || stringVariable || Returns the rightmost '''count''' characters of '''stringValue'''<br />
|-<br />
| string || replace || string;replace;searchText;replaceText;stringValue || stringVariable || Replaces '''searchText''' in '''stringValue''' with '''replaceText''' and returns the resulting string<br />
|-<br />
| string || replaceall || string;replace;searchText;replaceText;stringValue || stringVariable || Replaces all intances of '''searchText''' in '''stringValue''' with '''replaceText''' and returns the resulting string '''''Requires 1.2.9+'''''<br />
|-<br />
| string || trim || string;trim;stringValue || stringVariable || Removes leading and trailing spaces from stringValue and returns the result. <br />
|-<br />
| string || substring || string;substring;start;count;stringValue || stringVariable || Returns '''count''' characters starting at '''start''' from '''stringValue'''<br />
|-<br />
| 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.<br />
|-<br />
| string || tolowercase || string;tolowercase;stringValue || stringVariable || Converts the passed string to lower case and assigns to the passed variable name. <br />
|-<br />
| string || touppercase || string || stringVariable || Converts the passed string to upper case and assigns to the passed variable name. <br />
|-<br />
| 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. <br />
|-<br />
| 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.<br />
|-<br />
| 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'''.<br />
|-<br />
| turnorder || clear || none || none || Clears all entries from the {{Turn Tracker}}/Initiative<br />
|-<br />
| turnorder || addtoken || tokenid;trackervalue || none || Adds the token represented by "tokenid" to the initiative tracker with an initiavie value of "trackervalue"<br />
|-<br />
| turnorder || replacetoken || tokenid;trackervalue || none || Replaces the token represented by "tokenid" in the initiative tracker with an initiavie value of "trackervalue". Will add the token if it doesn't exist in the tracker.<br />
|-<br />
| turnorder || removetoken || tokenid || none || Removes the token represented by "tokenid" from the initiative tracker if it exists<br />
|-<br />
| turnorder || addcustom || textlabel;trackervalue || none || Add a custom text entry to the {{Turn Tracker}}/Initiative named "textlabel" with an initiative value of "trackervalue"<br />
|-<br />
| system || date || getdatetime || stringVariable || Returns the date time in the active timezone (see settings) <br />
|-<br />
| system || date || getdate || stringVariable || Returns the date in the active timezone (see settings) <br />
|-<br />
| system || date || gettime || stringVariable || Returns the time in the active timezone (see settings)<br />
|-<br />
| system || dumpvariables || "rolls", "string", or "array" || none || Dumps all of the defined variables of the indicated type to the console log<br />
|-<br />
| system || findability || system;findability;charactername;abilityname || stringVariable || Returns the object ID of the ability on the indicated character or "AbilityNotFound"<br />
|-<br />
|}<br />
<br />
Examples:<br />
<br />
<pre><br />
--~HowFarAway|distance;@{selected|token_id};@{target|token_id}<br />
</pre><br />
<br />
Returns the distance (Chebyshev) between the selected and target tokens and stores it in "HowFarAway".<br />
<br />
<pre><br />
--SelectedDudes|getselected<br />
</pre><br />
<br />
If 5 tokens were selected, 6 variables would be created: SelectedDudesCount (with a value of 5), SelectedDudes1, SelectedDudes2, SelectedDudes3, SelectedDudes4, SelectedDudes5.<br />
<br />
=== Information Request (--i) ===<br />
<br />
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.<br />
<br />
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.<br />
<br />
After the user has clicked the button and responded to the requests, ScriptCards will resume processing the script from where it left off.<br />
<br />
Here is an example “i” line:<br />
<br />
<pre><br />
--IScriptCards needs additional information to continue;Click to select a target and provide information|t;MyNewTarget;Missile1Target||q;MyNameIs;What is your name?<br />
</pre><br />
<br />
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.<br />
<br />
Supported information request types are “t” for target token, and “q” for query.<br />
<br />
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).<br />
<br />
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:<br />
<br />
<pre><br />
q;UserName;What is your name?|Fred|Bob|Sally|Nancy<br />
</pre><br />
<br />
Would have a dropdown menu with four choices.<br />
<br />
== Inline Formatting ==<br />
<br />
Inline formatting is processed on Direct Output lines only (--+ lines) and the following inline format markup is available:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Formatting Tags !! Description<br />
|-<br />
| [b]..[/b] || Bold the text between the markers <br />
|-<br />
| [i]..[/i] || Italicize the text between the markers <br />
|-<br />
| [u]..[/u] || Underline the text between the markers <br />
|-<br />
| [s]..[/s] || Strike-Thru the text between the markers <br />
|-<br />
| [c]..[/c] || Center alignment <br />
|-<br />
| [l]..[/l] || Left alignment <br />
|-<br />
| [r]..[/r] || Right alignment <br />
|-<br />
| [j]..[/j] || Full justification alignment <br />
|-<br />
| [#xxx]..[/#] or [#xxxxxx]..[/#] || Use a 3 or 6 digit hex code to colorize the text between the markers <br />
|-<br />
| [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, <code>[img width=128 height=128]</code> )<br />
|-<br />
| [button]caption::action[/button] || Create a button with the label "caption" that performs the action defined by "action". <br />
|-<br />
| [t] || Converted to HTML table tag. Text after the "t" will be included inside the tag (width, border, etc)<br />
|-<br />
| [/t] || Converted to HTML close table tag.<br />
|-<br />
| [tr] || Converted to HTML table row tag. Text after the "tr" will be included inside the tag<br />
|-<br />
| [/tr] || Converted to HTML close table row tag.<br />
|-<br />
| [td] || Converted to HTML table cell tag. Text after the "tr" will be included inside the tag<br />
|-<br />
| [/td] || Converted to HTML close table cell tag.<br />
|}<br />
<br />
== Variables ==<br />
<br />
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. While it is possible to assign both a string and a roll variable the same name, doing so will likely result in confusion when looking at the script later, so it is not recommended.<br />
<br />
String Variables are assigned with the --& statement and are referenced using [&variableName] notation.<br />
<br />
Roll Variables are assigned with the --= statement, and the assignment value is always processed by the ScriptCards Roll Processor (resolves dice rolls, etc.)<br />
<br />
There are a handful of variables assigned automatically when a ScriptCard is executed. These are all string variables, and are:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Variable !! Value<br />
|-<br />
| SendingPlayerID || Contains the object ID of the player that sent the macro<br />
|-<br />
| SendingPlayerName || Contains the display name of the player<br />
|-<br />
| SendingPlayerColor || Contains the color code associated with the player<br />
|-<br />
| SendingPlayerSpeakingAs || The contents of the "Speaking As" dropdown window<br />
|-<br />
| SendingPlayerIsGM || Contains 1 if the player is a GM, and 0 if the player is NOT a GM<br />
|}<br />
<br />
== Arrays ==<br />
<br />
Arrays are a special type of variable, and are managed by the function (<nowiki>--~</nowiki> command). All of the array function commands follow the same pattern:<br />
<br />
<pre>--~variableName|array;subcommand;arrayname;param1;param2;param3;...</pre><br />
<br />
Not all array commands return anything to "variableName". The function table above will specify the return type of the command if any.<br />
<br />
There are a couple of different ways to create an array:<br />
<br />
The '''define''' array subcommand creates (or recreates) an array and assigns it values - one for each included parameter after the array name. For example:<br />
<br />
<pre>--~|array;define;Fruits;mango;peach;strawberry;apricot;banana;apple</pre><br />
<br />
will create an array called '''Fruits''' with 6 elements in the order listed in the command (mango, peach, etc.)<br />
<br />
You can also use two other subcommands to create arrays based on tokens:<br />
<br />
<pre>--~Count|array;pagetokens;Everybondy;@{selected|token_id}</pre><br />
<br />
and<br />
<br />
<pre>--~Count|array;selectedtokens;Selected</pre><br />
<br />
In both cases, arrays of tokens will be created, and a string variable called "Count" will be set to the number of tokens in the array. The '''pagetokens''' command returns (by default) all of the tokens on the page that contains the token passed as the parameter after the array name. You can filter the tokens that "pagetokens" includes in the array by appending an optional parameter describing the type of token you are looking for:<br />
<br />
<pre>--~Count|array;pagetokens;Everybondy;@{selected|token_id};npc</pre><br />
<br />
Will return only tokens on the page that represent characters that do not have a ''controlledby'' parameter set. The available options are "all" (default), "char", "graphic", "pc", and "npc".<br />
<br />
The '''selectedtokens''' command returns an array with all of the tokens that were selected when the script was called.<br />
<br />
You can also use an arbitrary string to create an array, specifying a delimiter with the '''fromstring''' command:<br />
<br />
<pre><br />
--&names|Fred<br />
--&names|+,Sally<br />
--&names|+,Ted<br />
--&names|+,Joyce<br />
--~|array;fromstring;,;[&names]<br />
</pre><br />
<br />
The above example builds a comma-separated string and then uses "fromstring" to create an array with 4 elements from it, specifying the comma as the delimiter.<br />
<br />
Finally, you can use the '''statusmarkers''' command to create an array with one entry for each active status marker on a specified token:<br />
<br />
<pre>--~|array;statusmarkers;Conditions;@{selected|token_id}</pre><br />
<br />
will create an array with one entry for each status active on the selected token. The array elements will be the internal name of the status (if you are using custom status marker packs, the names will be specified in the marker pack).<br />
<br />
'''Traversing Arrays'''<br />
<br />
Each array keeps track of an internal index position (starting at 0). Several commands let you manage this index:<br />
<br />
*'''getindex''' returns the current index value<br />
*'''setindex''' sets the index to the specified location in the array<br />
*'''getlength''' returns the number of elements in the array<br />
*'''indexof''' returns the index location of the specified element<br />
<br />
Other commands let you retrieve values from the array:<br />
<br />
*'''getfirst''' sets the index to 0 and returns the value at that position<br />
*'''getnext''' advances the index by 1 and returns the new current value<br />
*'''getprevious''' reduces the index by 1 and returns the new current value<br />
*'''getlast''' sets the index to the last elements in the array and returns the new current value<br />
<br />
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.<br />
<br />
'''Manipulating Array Elements'''<br />
<br />
Several array commands deal with inserting, removing, and modifying elements:<br />
<br />
*'''add''' works just like define, except that it takes an existing array and adds elements to it based on the passed parameters<br />
*'''remove''' looks for items matching each passed parameter and removes them from the indicated array if they exist<br />
*'''removeat''' allows you to specify an index location in the array and remove the element at that position<br />
*'''replace''' searches an array for a value and replaces all occurrences of it with a new value (if found)<br />
*'''sort''' sorts the elements in the array in ascending order<br />
*'''strinfigy''' returns a string variable that includes each array element separated by semicolons (;) <br />
<br />
'''Referencing Array Elements'''<br />
<br />
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.<br />
<br />
<pre><br />
!script {{<br />
--~dummy|array;pagetokens;myarray;@{selected|token_id}<br />
--~count|array;getcount;myarray<br />
--+Total:|There are [&count] graphical objects on the page<br />
--~testvar|array;getfirst;myarray<br />
--:loop|<br />
--+Value|[*[&testvar]:character_name]<br />
--~testvar|array;getnext;myarray<br />
--?[&testvar] -ne ArrayError|loop<br />
--+Loop1|Is Done!<br />
}}<br />
</pre><br />
<br />
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:<br />
<br />
<pre><br />
!script {{<br />
--~dummy|array;pagetokens;myarray;@{selected|token_id}<br />
--~count|array;getcount;myarray<br />
--+Total:|There are [&count] graphical objects on the page<br />
--%loopCounter|1;[&count]<br />
--+Value|[*[@myarray([&loopCounter])]:character_name]<br />
--%|<br />
--+Loop|Is Done!<br />
}}<br />
</pre><br />
<br />
This line : <nowiki>--+Value|[*[@myarray([&loopCounter])]:character_name]</nowiki> uses [@arrayName(index)] format (inside a [*characterid:attribute] syntax) to perform the same task as running through the loop with the index.<br />
<br />
(Note: Additional examples are on the way...)<br />
<br />
== For...Next Loops ==<br />
<br />
For...Next loops in ScriptCards are supported with the with the --% statement type. A loop is defined by starting off with:<br />
<br />
<pre><br />
--%LoopCounter|<start>;<end>;[step]<br />
</pre><br />
<br />
The start and end values are required, while the step parameter is optional. If the step is omitted, it will be assumed to be 1. A string variable named after the line tag ("LoopCounter" in the case above) will be created and will hold the current iteration value for the loop. Here is a real example:<br />
<br />
<pre><br />
--%LoopCounter|1;10;1<br />
</pre><br />
<br />
This will begin a loop identified by "LoopCounter" that will start at 1, increasing by 1 each iteration (the step) until it has completed 10 executions.<br />
<br />
The "next" statement is simply <code>--%|</code>, with no tag or parameters. This indicates to ScriptCards that it should increment the counter and go back to the beginning of the loop. Extending the example above:<br />
<br />
<pre><br />
!script {{<br />
--%LoopCounter|1;10;1<br />
--=Roll|1d20<br />
--+Loop|Counter is [&LoopCounter], roll was [$Roll]<br />
--%|<br />
}}<br />
</pre><br />
<br />
The <code>--%!|</code> sequence will break out of the loop, no matter how many iterations are remaining.<br />
<br />
The % and %! character sequences can also be used as part of a 1.2.1+ non-branching conditional to continue or break the loop:<br />
<br />
<pre><br />
--?"X[&RollInto]X" -eq "XX"|%<br />
</pre><br />
<br />
In this example, if the string variable RollInfo is empty, the loop will return to the top and continue with the next iteration, while:<br />
<br />
<pre><br />
--?"X[&RollInto]X" -eq "XX"|%!<br />
</pre><br />
<br />
Would cause the whole loop to end if the condition were true.<br />
<br />
== Referencing ==<br />
<br />
=== Roll Variables===<br />
<br />
Roll Variables can be referenced from the content portion of any line type, and from the tag portion of conditional statements. The referenced value is replaced when the line is executed.<br />
<br />
There are several modifiers that can be used to reference parts of a roll:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Modifier !! Meaning<br />
|-<br />
| No modifier || In a Direct Output Line (<nowiki>--+</nowiki>), GM Output Line (<nowiki>--*</nowiki>), or String Assignement (<nowiki>--&</nowiki>), 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<br />
|-<br />
| .Total || The end result of the roll equation. Formatting rules for "No Modifier" apply based on line type. <br />
|-<br />
| .Raw || The total value of the roll variable without any formatting, no matter what kind of line the reference is used in.<br />
|-<br />
| .Base || The cumulative result of any dice rolled in the Roll Text (Numeric modifiers are not included) <br />
|-<br />
| .Ones || The number of dice in the roll that came up as 1s <br />
|-<br />
| .Aces || The number of dice in the roll that came up as the maximum number on the die <br />
|-<br />
| .Odds || The number of dice in the roll that came up with an odd number <br />
|-<br />
| .Evens || The number of dice in the roll that came up with an even number <br />
|-<br />
| .RollText || The raw text of the roll that was use to generate the results <br />
|-<br />
| .Text || A text representation of the results of the roll, including the numbers rolled for each die <br />
|-<br />
| .tableEntryText || The text portion of the result of a table roll<br />
|-<br />
| .tableEntryImgURL || The image source portion of the result of a table roll<br />
|-<br />
| .tableEntryValue || If the tableEntryText is purely numeric, will contain the numeric value<br />
|}<br />
<br />
=== String Variables ===<br />
<br />
To reference a string variable, use the notation [&variablename]. String variables can be referenced in direct output, roll variable assignment, and string variable assignment statements.<br />
<br />
=== Character/Token Attributes ===<br />
<br />
A character or token attribute can be referenced from content portion of any type of line and is substituted when the line is executed. The general format for referencing a character attribute is [*ID:attribute]. ID can be a token ID or a character ID (these start with a dash). Additionally if you have specified a sourceToken or targetToken, you can substitute "S" or "T" for the ID (for example [*S:npc_type] will retrieve the npc_type attribute from the source token.<br />
<br />
By default, all attribute references will be pulled from the '''''character''''' object that the ID represents (either directly or by being a Token ID that represents a character).<br />
<br />
Keep in mind, that if you want to access the "max" of a character attribute (for example, the max hit points), then you cannot trust the name that your roll20 character sheet shows you when you hover your mouse over the max hit points. For example, this reference will not work: [*S:hp_max]. Instead, you need to use this reference: [*S:hp^].<br />
<br />
If your ID refers to a token, token attributes can be accessed by preceding the attribute name with "t-", for example [*S:t-aura1_radius]. Supported token attributes are:<br />
<br />
{|<br />
| t-name || t-id || t-statusmarkers || t-bar1_value<br />
|-<br />
| t-bar1_max || t-bar2_value || t-bar2_max || t-bar3_value<br />
|-<br />
| t-bar3_max || t-top || t-left || t-width<br />
|-<br />
| t-height || t-rotation || t-layer || t-aura1_radius<br />
|-<br />
| t-aura1_color || t-aura2_radius || t-aura2_color || t-aura1_square<br />
|-<br />
| t-aura2_square || t-tint_color || t-light_radius || t-light_dimradius<br />
|-<br />
| t-light_angle || t-light_losangle || t-light_multiplier || t-light_otherplayers<br />
|-<br />
| t-light_hassight || t-flipv || t-fliph || t-controlledby<br />
|-<br />
| t-_cardid || t-_pageid || t-imgsrc || t-bar1_link<br />
|-<br />
| t-bar2_link || t-bar3_link || t-represents || t-layer<br />
|-<br />
| t-isdrawing || t-name || t-gmnotes || t-showname<br />
|-<br />
| t-showplayers_name || t-showplayers_bar1 || t-showplayers_bar2 || t-showplayers_bar3<br />
|-<br />
| t-showplayers_aura1 || t-showplayers_aura2 || t-playersedit_name || t-playersedit_bar1<br />
|-<br />
| t-playersedit_bar2 || t-playersedit_bar3 || t-playersedit_aura1 || t-playersedit_aura2<br />
|-<br />
| t-lastmove || t-adv_fow_view_distance || t-has_bright_light_vision || t-has_night_vision<br />
|-<br />
| t-night_vision_distance || t-emits_bright_light || t-bright_light_distance || t-emits_low_light<br />
|-<br />
| t-low_light_distance || t-has_limit_field_of_vision || t-limit_field_of_vision_center || t-limit_field_of_vision_total<br />
|-<br />
| t-has_limit_field_of_night_vision || t-limit_field_of_night_vision_center || t-limit_field_of_night_vision_total || t-has_directional_bright_light<br />
|-<br />
| t-directional_bright_light_center || t-directional_bright_light_total || t-has_directional_dim_light || t-directional_dim_light_center<br />
|-<br />
| t-directional_dim_light_total || t-lightColor || || |<br />
|}<br />
<br />
'''''It is important to note that some attributes names on tokens have corresponding attribute names on characters, which represent different values. For example, [*T:id] returns the character ID, while [*T:t-id] returns the token ID.'''''<br />
<br />
=== Subroutine Parameters ===<br />
<br />
When using a gosub statement (-->) or a conditional marked as a gosub (prefixing the label with a > character), you can pass any number of parameters separated by semicolons (;) that the code in the subroutine can utilize.<br />
<br />
Subroutine parameters are numbered starting at 1, and are accessed by using the notation [%number%], so the first parameter is [%1%], the second is [%2%], etc.<br />
<br />
Parameter substitution happens on all line types, and happens prior to character attribute references or roll variable substitution.<br />
<br />
=== Campaign Attribute ===<br />
You can retrieve properties of the API's Campaign object with the [*C:attributename] syntax. For example, [*C:playerpageid] will retrieve the current player ribbon page from the Campaign object.<br />
<br />
=== Page Attributes ===<br />
If you have set the '''activepage''' parameter, you can retrieve page-related properties with the [*P:attributename] syntax, including the page's UDL parameters.<br />
<br />
=== Repeating Section Values ===<br />
<br />
You can reference repeating attribute data using the syntax [*R:attributename] syntax (similar to referencing standard character attributes). The currently active repeating row information will be used to retrieve attribute values. You can also retrieve the full attribute name for a repeating row attribute by using the [*R>attributename] notation. This is useful to pass to things like chatsetattr.<br />
<br />
See the section named [[#Repeating Section Access (--R)|Repeating Section Access]] for more information.<br />
<br />
=== Array Elements ===<br />
After an array has been declared, the elements can be referenced with [@arrayName(index)]. Array indices start at 0.<br />
<br />
== Deferred Resolution for Meta Scripts ==<br />
<br />
As of 1.2.9, ScriptCards supports a deferral character for use when calling another API script with via the --@ statement, to defer processing of meta script references so they get processed prior to the sub-API call insted of prior to ScriptCards execution. To defer this processing for meta script (SelectManager, Fetch) by inserting a deferral character into the meta call. For example, if I want to have ScriptCards call TokenMod as if the token for "Quej Gr'stra" (yes, I let Roll20 name my test NPCs) I could use something like this:<br />
<br />
--@token-mod|{^& select Quej Gr'stra} _on showname<br />
<br />
The "^" in between { and & will prevent SelectManager from seeing the call when the ScriptCard script is processed, but the --@ statement will remove the deferral character so the command that will be sent by ScriptCards is:<br />
<br />
!token-mod {& select Quej Gr'stra} --on showname<br />
<br />
With the deferral character removed, SelectManager will see the {& select ...} and do its magic.<br />
<br />
While the default deferral character is "^", the deferral character is a setting that can be changed:<br />
<br />
--#deferralcharacter|%<br />
<br />
Will make % the deferral character for future --@ statements in the running script.<br />
<br />
There are currently three supported Meta script structures: {^&...} for SelectManager, @^(...) and *^(...) for fetch, where the ^ in the structures here represents the placement of the deferral character.<br />
<br />
== Arrays ==<br />
<br />
Arrays are a new data type introduced in version 1.1.12 of ScriptCards, and are manipulated with associated function (--~) commands.<br />
<br />
* Arrays are a lists of strings. Items in an array cannot contain the semi-colon (;) character, as that is used to separate parameters in the function code that deals with arrays.<br />
* Arrays are accessed via the --~ script command. In some cases, the value of the tag (variable name) for array commands is not used, and can be a dummy value or simply omitted. I have omitted them in the statements below.<br />
* All commands that DO return a value return string values, even if the content is numeric.<br />
* If a command returns a value and there is some sort of reason that it isn't an array value, you will get "ArrayError" in the return value. This can happen if you reach the end of an array while stepping through it, for example, so checking for "ArrayError" can serve as the end condition for a loop.<br />
* Each array keeps track of its current index, allowing you to step forward and backwards through arrays.<br />
* Any number of arrays can be defined.<br />
* Unlike string variables and roll variables, array variables cannot (currently) be referenced directly. It is necessary to use the function (--~) syntax to manipulate arrays and get values from them as strings for use in other parts of your script.<br />
<br />
<br />
== Reentrant Scripts ==<br />
<br />
Reentrant scripts allow you to create buttons in your script code that will re-execute the script at a given label within the code. If you set the reentrant setting (--#reentrant|somevalue) to a non-zero value, your setting and variable information will be preserved between executions. Reentrant script can be used to present menus or choices and then continue acting.<br />
<br />
Reentrant buttons are created with the [rbutton]Caption::ReentryLabel;Parameter[/rbutton] construct. The caption will be displayed on the generated button. ReentryLabel is the name of a label in your script that the button will jump to when clicked, and Parameter will be passed in as a string value called "reentryval".<br />
<br />
Example:<br />
<pre><br />
!script {{<br />
--#reentrant|testing<br />
--=Roll|1d20<br />
--+Roll|[$Roll]<br />
--&String|That was a [$Roll.Raw]!<br />
--~x|array;define;MyArray;Apple;Banana;Orange<br />
--+Try it|[rbutton]Hello!::EXEC_PC_SPELL;9[/rbutton]<br />
--X|<br />
<br />
--:EXEC_PC_SPELL|<br />
--+ReentryVal|[&reentryval]<br />
--+The value of Roll is|[$Roll]<br />
--+Value of String|[&String]<br />
--+Array|[@MyArray(0)]<br />
--X|<br />
}}<br />
</pre><br />
<br />
This script sets up some variables and then displays a button labeled "Hello!". If the user clicks the button, the script will be re-entered starting at the "EXEC_PC_SPELL", which will display the content of the variables from the original execution.<br />
<br />
'''''Note: This section needs to be expanded upon'''''<br />
<br />
== Procedure Libraries ==<br />
<br />
You can now create handouts in your game in Roll 20 with the name format "ScriptCards Library NAME", where name is a name you assign to the library. Library names are case sensitive. It is my hope that the more proficient ScriptCards scripters out there will provide procedure libraries (or procedures that can be included in libraries) for others to use to make their scripting life easier. Be they specific to a game system, or to a type of activity, I think a robust set of libraries that GMs could use to enhance their scripting capabilities would be very valuable to the community. Should such things begin to emerge, I’ll create a portion of the ScriptCards Wiki page to house them.<br />
<br />
To include one or more libraries in a script, use the +++libname+++ directive (does not need a -- line associated with it). Multiple library names can be specified by separating them with semicolons (i.e., +++General;dnd5elib;Colorize+++ would include three libraries (General, dnd5elib, and Colorize).<br />
<br />
Included libraries are separated from the main script code by the automatic inclusion of "--X|" before the first library is appended to the script, and all libraries are loaded at the end of the script before script processing takes place.<br />
<br />
Procedures and labels in libraries can be used just as if they were included in the body of your script. Note that this DOES mean that you could, technically, jump into a library with a direct branch (--^) or direct branch conditional, but I recommend using libraries to store reusable procedures.<br />
The Notes section of the library handout stores the library code, and is written just like any other ScriptCards code except:<br />
<br />
* They cannot use roll queries (?{Some Prompt:}) to get information from the user at execution time.<br />
* They cannot use @{} notation to access character and token information.<br />
<br />
Both of these limitation stem from the fact that Procedure Libraries are not processed by the chat server, which is what handles these items.<br />
<br />
Here is an example of handling damage modifications (resistance, vulnerability, and immunity) in D&D 5E with a library:<br />
<br />
<pre><br />
!script {{<br />
+++dnd5elib+++<br />
--#|Damage Modifiers Test<br />
--#targettoken|@{target|token_id}<br />
-->Lib5E_CheckDamageModifiers|ResistType;fire<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] fire damage<br />
<br />
-->Lib5E_CheckDamageModifiers|ResistType;cold<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] cold damage<br />
<br />
-->Lib5E_CheckDamageModifiers|ResistType;poison<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] poison damage<br />
<br />
-->Lib5E_CheckDamageModifiers|ResistType;acid<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] acid damage<br />
<br />
--X|<br />
}}<br />
</pre><br />
<br />
Library content (In a handout called “ScriptCards Library dnd5elib” NOTE: Paste into Notepad first and then paste into the handout in Roll20 to avoid bringing over HTML formatting from the web site):<br />
<br />
<pre><br />
--/|ScriptCards Library: dnd5elib version 0.0.1<br />
--/|Provides various utility procedures for D&D 5E games<br />
<br />
--/|Lib5E_CheckDamageModifiers handle damage resistance, vulnerability, and immunity. <br />
--/|Pass a string variable to be filled with a string to be appended to a dice roll and the damage type <br />
<br />
--:Lib5E_CheckDamageModifiers|damageVariableName;damageType<br />
--&[%1%]|<br />
--?"[*T:npc_vulnerabilities]" -inc "[%2%]"|>_Lib5E_IsVulnerable;[%1%]<br />
--?"[*T:npc_resistances]" -inc "[%2%]"|>_Lib5E_IsResistant;[%1%]<br />
--?"[*T:npc_immunities]" -inc "[%2%]"|>_Lib5E_IsImmune;[%1%]<br />
--<|<br />
<br />
--:_Lib5E_IsVulnerable| --&[%1%]| * 2 [Vulnerable] --<|<br />
--:_Lib5E_IsResistant| --&[%1%]| \ 2 [Resistant] --<|<br />
--:_Lib5E_IsImmune| --&[%1%]| * 0 [Immune] --<|<br />
</pre><br />
<br />
The idea is that the functions in the library create a string that can be appended to a roll to modify the output based on resistances, so you pass Lib5E_CheckDamageModifiers the name of the string variable you want to use and the damage type. The variable (ResistType in this case) will include either nothing, “* 2 [Vulnerable]”, “\ 2 [Resistant]”, or “* 0 [Immune]” which can be included in a roll assignment (--=) to modify the damage as appropriate. The order here might be important if an NPC is misconfigured to be both resistant and immune to the same damage type. Since immune is an absolute, having it last ensures that it will override resistant or vulnerable. A creature that is both vulnerable and resistant (again, misconfigured) will come back as resistant since that condition is checked after vulnerable.<br />
Some notes: I prefix my library labels with either “Lib5E_” or “_Lib5E_” as a clarity convention. This isn’t strictly necessary but you should be aware that if two libraries (or if your script and a library) define the same label, the last label defined will win. Since libraries are appended to the end of the script in the order you include them in the +++libname+++ directive, you can somewhat control this, but it is probably best to avoid re-declaring labels. <br />
<br />
In my case, items beginning with “Lib5E_” are intended to be called by scripts, while items beginning with “_Lib5E_” are intended to be used as subroutines by the “public” procedures. Of course, there is no reason you couldn’t call them directly.<br />
<br />
You might also note that I’ve included some library information in comment lines (--/|) at the top of the library. These are ignored by ScriptCards, and are a good way to convey requirements, parameters, usage information, etc.<br />
<br />
== Example Libraries ==<br />
<br />
=== dnd5elib ===<br />
<br />
[https://github.com/kjaegers/ScriptCards Download the dnd5elib Library from the ScriptCards GitHub]<br />
<br />
The '''dnd5elib''' library provides a collection of utility procedures that help simplify dealing with the D&D 5E Official Sheet. Some of the procedures in this library require '''chatsetattr''' to be installed in your game. This is a growing library, and currently only has a handful of routines. They are:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Procedure Name !! Notes<br />
|-<br />
| style="white-space:nowrap" | Lib5E_CheckDamageModifiers || This procedure can be used to evaluate vulnerabilities, resistances, and invulnerabilities on an NPC. After setting the --#target| parameters, pass the Lib5E_CheckDamageModifiers procedure a variable name (no reference information) and a damage type (i.e., fire, cold, bludgeoning, etc.) and a string variable with the name passed in as the first parameter will be created that contains text that can be included in a roll line (--=) in order to modify the roll as appropriate. For example, '''-->Lib5E_CheckDamageModifiers|ResistType;fire''' will check the current target character's attributes for "fire" and will either return an empty string (no references), "* 0 [Immune]" if the creature is immune, "\ 2 [Resistant]" if the creature is resistant, or "* 2 [Vulnerable]" if the creature is vulnerable to fire damage.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_DeductSpellSlot || Pass in a character_id and a slot level, and the script will expend one spell slot of that level, capping the value at 0 slots remaining. For Example '''<nowiki>-->Lib5E_DeductSpellSlot|@{selected|character_id};1</nowiki>''' to deduct a first level spell slot from the selected character.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_FindResource || Used to locate a resource value on a character. Pass in a character_id, a resource name, and two variable names. The procedure will check both repeating and non-repeating resources looking for a resource whose name matches what was passed in and return three variables. The first will be a string variable named for the 3rd parameter and contains the attribute name of the resource's "name" field. The second will be a string variable named after parameter 4 and contains the resource's value field attribute name, and the third variable is a Roll Variable, also named after the 4th parameter that contains the current resource value. Example: '''<nowiki>-->Lib5E_FindResource|@{selected|character_id};Crossbow bolts;ResName;ResValue</nowiki>''' will find "Crossbow bolts" as a resource on the character and return [&ResName] which is the name of the resource attribute, [&ResValue] which is the '''name of the attribute that stores the value''' and [$ResValue] which is the current numeric value of the resource.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Global_Attack_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Attack Modifiers (repeating_tohitmod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Bless" for 1d4 active and "Being Cool" for +2 active, I will get a return string " + 1d4 [Bless] + 2 [Being Cool]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Save_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Save Modifiers (repeating_savemod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Bless" for 1d4 active and "Being Cool" for +2 active, I will get a return string " + 1d4 [Bless] + 2 [Being Cool]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Skill_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Skill Modifiers (repeating_skillmod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Guidance" for 1d4 active and "Being Cool" for +2 active, I will get a return string " + 1d4 [Guidance] + 2 [Being Cool]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_AC_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Save Modifiers (repeating_savemod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Shield of Faith" with a value of 2 active, I will get a return string " + 2 [Shield of Faith]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Damage_Modifiers || Pass a character ID and TWO string variable to set the return value. The first string will be for normal damage, and the second will be the additional damage on a crit. This procedure will look through the Global Damage Modifiers (repeating_damagemod_*) for rows that are active (checked on the character sheet) and return two strings with the dice rolls and descriptions for them (for example, if I have "Sneak Attack" with a value of 1d6 normal and 1d6 critical damage active, I will get a return string " + 1d6 [Sneak Attack]" and another string of " + 1d6 [Sneak Attack CRIT]" that can be used in a dice rolls.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_DivineSmiteDice || Used to calculate the number of dice to be rolled for a paladin's Divine Smite. Pass a target token id, a spell slot level, and a string variable to be set to the dice roll amount based on the NPC_TYPE attribute of the target token. The returned variable will contain a dice roll (like "3d8" that can be used in a --= line)<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Character_Summary || Pass a character ID to outputs a mini character sheet, including clickable buttons for attacks, actions, legendary actions, etc. Will automatically detect a PC vs NPC and output the appropriate sections.<br />
|}<br />
<br />
Due to formatting issues with the Wiki, the library code has been moved to a [https://gist.github.com/kjaegers/52f6049ddd257f0a1288aca4bbde13c5 GITHUB GIT]. Please view the GIST in raw mode and copy the text and paste it into a handout called "ScriptCards Library dnd5elib" in your Roll20 Game.<br />
<br />
== What to Know if you are Coming from PowerCards ==<br />
<br />
''Note: This section is a work in progress.''<br />
<br />
While ScriptCards and PowerCard have very similar output goals, their internals and use are quite different. The table below summarizes some of the major differences between the scripts.<br />
<br />
::{| class="wikitable"<br />
|-<br />
! PowerCards !! ScriptCards <br />
|-<br />
| With a handful of exceptions, all lines in a PowerCard macro are intended to produce a line of output on the final card. || With ScriptCards, ONLY the <code>--+</code> and <code>--*</code> statement types produces output <br />
|-<br />
| PowerCards lines begin with two dashes (<code>--</code>) followed by a unique tag name for the line, followed by a vertical bar and the content for the line. || ScriptCards lines begin with two dashes (<code>--</code>) followed by a '''statement type identifier''', which is a single character that identifies the type of line to the interpreter. This is followed by a tag (frequently optional), a vertical bar, and the parameters for the statement being executed.<br />
|-<br />
| PowerCard macros are always processed top to bottom. Lines can be hidden so they don't output anything, but there is no looping or branching (--SkipTo looks like a branch, but it just hides all of the lines until the referenced label. || ScriptCards scripts support true branching, including direct branching (<code>--^</code>) and procedure branching (<code>--></code>) and (<code>--<</code>). Procedures support parameters and a call stack so procedures can be nested to call other procedures.<br />
|-<br />
| All lines in a PowerCards macro need to have unique tags because PowerCards builds the card as a single JavaScript object using the tag names to store what will be displayed. This is why repeated tag names always result in the last one being shown. || ScriptCards tags do not need to be unique, and in the case of many line types are optional.<br />
|-<br />
| PowerCards conditionals result in either showing or hiding the line they are on. || ScriptCards conditionals '''''only''''' support branching as the result of the comparison. This branching can be direct (a GOTO) or procedural (a GOSUB) '''''NOTE: As of version 1.2.0, ScriptCards also supports roll/string variable assignment as a result of conditional evaluation'''''<br />
|-<br />
| PowerCards relies on the Roll20 [[Quantum Roll]] server and inline rolls for all dice functions || ScriptCards includes its own dice roll parser, and '''''does not support''''' inline rolls.<br />
|-<br />
| PowerCards RollIDs (often mistaken for variables) are assigned by analyzing the results of an inline roll, and cannot be referenced in other rolls, so you can't roll a <code>1d4</code> and then roll a <code>1d20</code> and add the <code>1d4</code> result because all of the rolls happen on the chat server before PowerCards gets the macro text. || ScriptCards supports two types of variables: Roll Variables and String Variables. Because ScriptCards uses its own roll parser and is not dependent upon the chat server, rolls and their results can be used in other rolls, math functions, output, etc.<br />
|}<br />
<br />
== Example Scripts ==<br />
<br />
Below are some sample scripts that utilize the various statement types in ScriptCards:<br />
<br />
=== Divine Smite ===<br />
<br />
This script will prompt the user for a spell slot level to expend on a divine smite. It will check the target's npc_type to see if it is an Undead or Fiend, which adds an additional d8 to the smite roll.<br />
<br />
[[File:ScriptCards Divine Smite.png|Divine Smite Script Output]]<br />
<br />
<pre><br />
!scriptcard {{<br />
--#title|Divine Smite<br />
--=DiceCount|?{Spell Slot Level?|1|2|3|4|5|6|7|8|9} + 1<br />
--=IsFiendOrUndead|0<br />
--?"@{target|npc_type}" -inc fiend|>IsBoosted<br />
--?"@{target|npc_type}" -inc undead|>IsBoosted<br />
--=TotalDice|[$DiceCount] + [$IsFiendOrUndead]<br />
--=SmiteRoll|[$TotalDice]d8<br />
--#emoteText|@{selected|token_name} smites @{target|token_name}<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
--+Smite|deals [$SmiteRoll] radiant damage.<br />
--X|<br />
<br />
--:IsBoosted|<br />
--=IsFiendOrUndead|1<br />
--<|<br />
}}<br />
</pre><br />
<br />
==== How It Works ====<br />
<br />
The first line sets the "title" card parameter to "Divine Smite".<br />
<br />
Line 2 Shows a query to the user asking for the spell slot level, adds one and stores the value in the "DiceCount" Roll Variable. The query/dropdown is generated by the chat server prior to the script being executed.<br />
<br />
Line 3 defaults the "IsFiendOrUndead" Roll Variable to 0.<br />
<br />
Lines 4 and 5 compare the target's "npc_type" attribute (passed by the chat server as text) to see if they include either "undead" or "fiend". If true, the IsBoosted subroutine will be called. No parameters are passed to this subroutine.<br />
<br />
Line 6 sets the "TotalDice" variable to the base (DiceCount) number plus the IsFiendOrUndead number, which will be a 0 or a 1.<br />
<br />
Line 7 calculates "SmiteRoll" by rolling a number of d8 equal to the "TotalDice" value.<br />
<br />
Lines 8-10 set the parameters for the emote, which appears above the card content. By setting the sourceToken and the targetToken, their icons will appear in the emote surrounding the text describing the action.<br />
<br />
Line 11 is the only line that actually produces output on the card. It results in "Smite deals # radiant damage".<br />
<br />
Line 12 ends the script execution, preventing the script from continuing and running the subroutines out of context.<br />
<br />
Lines 14-16 are the IsBoosted subroutine, starting with the :IsBoosted label. The IsFiendOrUndead variable is set to 1, and a return from subroutine is executed.<br />
<br />
=== Magic Missile ===<br />
<br />
This script demonstrates using a loop and calling a subroutine to fire a number of missiles determine by the spell slot level used to cast the spell.<br />
<br />
[[File:ScriptCards_MagicMissile_Fixed.png|Magic Missile Script Output]]<br />
<br />
<pre><br />
!scriptcard {{ <br />
--#title|Magic Missile<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
--=MissileCount|?{Spell Slot Level?|1|2|3|4|5|6|7|8|9} + 2<br />
--=DisplayCount|1<br />
--=MissileDamage|0<br />
--#leftsub|Slot level ?{Spell Slot Level?}<br />
--#rightsub|Ranged Attack<br />
--#emoteText|Fred uses a level ?{Spell Slot Level?} spell slot to fire [$MissileCount.Total] missiles of magical force!<br />
--:MissileLoop|<br />
-->FireMissile|<br />
--=DisplayCount|[$DisplayCount] + 1<br />
--?[$DisplayCount] -le [$MissileCount]|MissileLoop<br />
--+Total|Total damage is [$MissileDamage]<br />
--X|<br />
<br />
--:FireMissile|<br />
--=ThisMissile|1d4 + 1<br />
--=MissileDamage|[$MissileDamage] + [$ThisMissile]<br />
--+Missile|[$DisplayCount.Total] Hits for [$ThisMissile] [b]force[/b] damage<br />
--<|<br />
}}<br />
</pre><br />
<br />
==== How It Works ====<br />
<br />
Lines 1-3 set the card title, the source token and the target token. Setting these tokens causes their icons/avatars to appear in the Emote section of the card.<br />
<br />
Line 4 asks the user what spell slot level they wish to use to cast magic missile. The number of missiles fired is equal to 2 plus the spell level, and this is stored in the MissileCount variable.<br />
<br />
Line 5 stores a 1 in the DisplayCount variable. This will be used to control the loop to determine the number of missiles fired and the missile number when displaying damage rolls.<br />
<br />
Line 6 initializes MissileDamage to 0<br />
<br />
Line 7 sets the left subtitle to the text "Slot Level #", where # is the spell slot level being used.<br />
<br />
Line 8 sets the right subtitle to the text "Ranged Attack".<br />
<br />
Line 9 sets the emoteText parameter with a description of the action, including the slot level and number of missiles fired.<br />
<br />
Line 10 is a label for the missile firing loop<br />
<br />
Line 11 Calls the "FireMissile" subroutine<br />
<br />
Line 12 increases the DisplayCount variable by 1<br />
<br />
Line 13 Checks to see if there are still missles to fire (DisplayCount <= MissileCount) and if so branches to MissileLoop<br />
<br />
Line 14 Displays the total damage dealt by the spell.<br />
<br />
Line 15 stops execution of the script to prevent out of context execution of the subroutine.<br />
<br />
Lines 76-21 are the FireMissile subroutine, beginning with the FireMissile label. The 1d4+1 is rolled and assigned to "ThisMissile". The result is added to the existing MissileDamage total, and a line for the current missile is displayed with the missile number and the damage for the missile.<br />
<br />
=== Longsword Attack ===<br />
<br />
This script demonstrates a standard 5E D&D melee weapon attack, including detection of misses, fumbles, hits, and critical hits. If installed, alterbars is used to decrement the target's BAR3 value by the damage dealt.<br />
<br />
[[File:ScriptCards Longsword.png|Longsword Script Output]]<br />
<br />
<pre><br />
!scriptcard {{<br />
--#title|Longsword<br />
--#leftsub|Melee Attack<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
--#emoteText|@{selected|token_name} attacks @{target|token_name}<br />
--=TargetAC|@{target|npc_ac}<br />
--?[$TargetAC.Total] -gt 0|DoneWithAC<br />
--=TargetAC|@{target|ac}<br />
--:DoneWithAC|<br />
--=AttackRoll|1d20 + @{selected|strength_mod} [STR] + @{selected|pb} [PROF]<br />
--+Attack|@{selected|token_name} rolls [$AttackRoll] vs AC [$TargetAC].<br />
--?[$AttackRoll.Base] -eq 20|Crit<br />
--?[$AttackRoll.Base] -eq 1|Fumble<br />
--?[$AttackRoll.Total] -ge [$TargetAC.Total]|Hit<br />
--+Miss|The attack missed.<br />
--^Final|<br />
<br />
--:Fumble|<br />
--+Fumble!|The attack went horribly wrong.<br />
--^Final|<br />
<br />
--:Hit|<br />
--=Damage|1d8 + @{selected|strength_mod} [STR]<br />
--+Hit!|The attack hit @{target|token_name} for [$Damage] slashing damage.<br />
--@alter|_target|@{target|token_id} _bar|3 _amount|-[$Damage]<br />
--^Final|<br />
<br />
--:Crit|<br />
--=Damage|1d8 + @{selected|strength_mod} [STR] + 1d8 [CRIT]<br />
--+Critical Hit!|The attack hit @{target|token_name} for [$Damage] slashing damage.<br />
--@alter|_target|@{target|token_id} _bar|3 _amount|-[$Damage]<br />
<br />
--:Final|<br />
}}<br />
</pre><br />
<br />
==== How it Works ====<br />
<br />
In lines 1-5, we set the title, subtitle, and emote text along with the tokens for the emote area.<br />
<br />
Lines 6-9 allow us to determine the AC of the target. On the 5E Roll20 sheet, NPCs armor class is stored in "npc_ac", while PCs armor class is in "ac". First we grab npc_ac and if it is zero, we check AC.<br />
<br />
Line 10 rolls the attack roll, rolling 1d20 and adding the attacker's strength modifier and proficiency bonus<br />
<br />
Line 11 displays the result of the attack roll on the card<br />
<br />
Lines 12-14 determine what kind of result the attack had. If the .Base value of the roll was 20, we branch to "Crit". If it was 1, we branch to "Fumble". If the .Total value of the roll was greater than or equal to the AC that was determined in Lines 6-9, we branch to Hit.<br />
<br />
Assuming we didn't branc anywhere, the result of the attack was a miss, so we display that on line 15 and then branch to "Final"<br />
<br />
This is followed by three branch segments, :Fumble, :Hit, and :Crit. A fumble displays a text message and branches to :Final.<br />
<br />
On a hit or a crit, we roll Damage (adding additional damage dice on a crit). We display a "Hit!" or "Critical Hit!" message and then make an API call to AlterBars, passing it the token id, bar we want to modify (3 in this case), and the amount we want to modify by the Damage value.<br />
<br />
=== Party Health Status ===<br />
<br />
This example calculates the current Hit Points remaining and HP percentage for each character and creates a color-coded display with the current party status.<br />
<br />
[[File:ScriptCards Party Health.png]]<br />
<br />
<pre><br />
!scriptcard {{<br />
--#title|Party Status<br />
--#titleCardBackground|#33CC33<br />
--#oddrowbackground|#bfee90<br />
--#evenrowbackground|#90eebf<br />
-->HealthCheck|@{Quej Grastra|character_id}<br />
-->HealthCheck|@{Brim Cheuto|character_id}<br />
-->HealthCheck|@{Odug Ututees|character_id}<br />
--X|End of card Execution<br />
<br />
--:HealthCheck|<br />
--=HealthPerc|[*[%1%]:hp] / [*[%1%]:hp^] * 100 \ 1<br />
--=HealthColor|000000<br />
--?[$HealthPerc.Total] -gt 50|HealthSkip<br />
--=HealthColor|FF0000<br />
--:HealthSkip|<br />
--+[*[%1%]:character_name]|has [#[$HealthColor.RollText]][*[%1%]:hp] of [*[%1%]:hp^][/#] HP [R]([$HealthPerc.Total]%)[/R]<br />
--<|End of HealthCheck<br />
}}<br />
</pre><br />
<br />
==== How it Works ====<br />
<br />
Lines 1-4, we set the card title, and set the title background and row background colors to shades of green.<br />
<br />
Lines 5-7 make gosub calls the the "HealthCheck" subroutine, passing in the character ID of each of the named characters (these are the names of the characters in my test game)<br />
<br />
Line 8 terminates the script execution.<br />
<br />
The remaining lines of the script are the HealthCheck subroutine, which works like this:<br />
<br />
Line 10 is the subroutine label (:HealthCheck)<br />
<br />
Line 11 uses the character id passed as a parameter and combines it with character attribute lookup *(...) to retrieve the value of "hp" and "hp<nowiki>^</nowiki>" for the character. The <nowiki>^</nowiki> character is used to specify that we want the MAX value for this attribute for the second call. We divide these two numbers and multiple by 100 to get a percentage. Finally, we use integer division by 1 to round the percentage and drop the decimals. The end result gets stored in the HealthPerc roll variable.<br />
<br />
Line 12 defaults to color of the health text to black<br />
<br />
Line 13 check to see if the health percentage is greater than 50. If so, it branches to HealthSkip, preventing the script from executing line 13.<br />
<br />
Line 14 sets the color of the health text to red<br />
<br />
Line 15 is the label that will be branched to from Line 13 to skip the red coloring<br />
<br />
Line 16 again uses character attribute substitution and the passed parameter value to output a display line containing the character name, the colorized health total, and the percentage value. The percentage is right-justified.<br />
<br />
Line 17 returns from the HealthCheck subroutine.<br />
<br />
=== Expanded Magic Missile Script ===<br />
<br />
This is the expanded and enhanced version of the Magic Missile script covered in {{yt|watch?v=u50xvNzS9Zk | this video}}. It includes visual and audio effects, checking and deducting spell slots, and applying damage using either Token-Mod or Alterbars.<br />
<br />
<pre><br />
!scriptcard {{ <br />
--#title|Magic Missile<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
<br />
-->GetAndCheckSlotInformation|<br />
<br />
--=MissileCount|[$SlotLevel] + 2<br />
--=DisplayCount|1<br />
--=MissileDamage|0<br />
--#leftsub|Slot level [$SlotLevel]<br />
--#rightsub|Ranged Attack<br />
--#emoteText|@{selected|character_name} uses a level [$SlotLevel.Total] spell slot to fire [$MissileCount.Total] missiles of magical force!<br />
<br />
--:MissileLoop|<br />
-->FireMissile|<br />
--=DisplayCount|[$DisplayCount] + 1<br />
--?[$DisplayCount] -le [$MissileCount]|MissileLoop<br />
--+Total|Total damage is [$MissileDamage]<br />
-->DeductSpellSlot|<br />
--#rightsub|Level [$SlotLevel] Left: [$SlotsRemaining] <br />
-->PlayEffects|none;burst-smoke;beam-magic;spell_01<br />
-->ApplyDamageTokenmod|@{target|token_id};3;-[$MissileDamage]<br />
-->ApplyDamageAlterbars|@{target|token_id};3;-[$MissileDamage]<br />
--X|<br />
<br />
--:FireMissile|<br />
--=ThisMissile|1d4 + 1<br />
--=MissileDamage|[$MissileDamage] + [$ThisMissile]<br />
--+Missile|[$DisplayCount.Total] Hits for [$ThisMissile] [b]force[/b] damage<br />
--<|<br />
<br />
--:GetAndCheckSlotInformation|<br />
--=SlotLevel|?{Spell Slot Level?|1|2|3|4|5|6|7|8|9}<br />
--=SlotsTotal|[*S:lvl[$SlotLevel]_slots_total]<br />
--=SlotsExpended|[*S:lvl[$SlotLevel]_slots_expended]<br />
--?[$SlotsExpended.Total] -ge [$SlotsTotal.Total]|NoSlotsLeft<br />
--<|<br />
<br />
--:NoSlotsLeft|<br />
--+|[*S:character_name] has no level [$SlotLevel.Total] spell slots available.<br />
--X|<br />
<br />
--:DeductSpellSlot|<br />
--=SlotsExpended|[$SlotsExpended] + 1<br />
--@setattr|_charid [*S:character_id] _lvl[$SlotLevel]_slots_expended|[$SlotsExpended] _silent<br />
--=SlotsRemaining|[$SlotsTotal] - [$SlotsExpended]<br />
--<|<br />
<br />
--:PlayEffects|Parameters are : source effect; target effect; line effect; sound effect<br />
--vtoken|@{selected|token_id} [%1%]<br />
--vtoken|@{target|token_id} [%2%]<br />
--vbetweentokens|@{selected|token_id} @{target|token_id} [%3%]<br />
--@roll20AM|_audio,play,nomenu|[%4%]<br />
--<|<br />
<br />
--:ApplyDamageTokenmod|Parameters are tokenid;bar#;amount<br />
--@token-mod|_ignore-selected _ids [%1%] _set bar[%2%]_value|[%3%]<br />
--<|<br />
<br />
--:ApplyDamageAlterbars|<br />
--@alter|_target|[%1%] _bar|[%2%] _amount|[%3%]<br />
--<|<br />
}}<br />
</pre><br />
<br />
[[Category:Featured articles]]</div>5004103https://wiki.roll20.net/Script:ScriptCardsScript:ScriptCards2021-10-01T10:29:52Z<p>5004103: /* Repeating Section Access (--R) */</p>
<hr />
<div>{{revdate}}<br />
== Introduction ==<br />
'''ScriptCards''' provides a script interpreter that can be used to create powerful macros that display the results of player/NPC actions, or display other information in a pleasing visual format in your game's chat window. The scripting language contains variables (both dice-roll (enhanced numerics) and strings) as well, conditionals, branching, subroutines with parameters, and a set of built-in functions to simplify working with Roll20 information.<br />
{{script overview<br />
|name=ScriptCards<br />
|author={{user profile|2365448|Kurt J.}}<br />
|code=<br />
|version=1.4.0e<br />
|lastmodified=2021-09-24}}<br />
ScriptCards is not game-system specific, and can be used with any system/sheet. Near the end of this Wiki there is a section set aside for libraries that can implement system-specific tasks, with the hope that enthusiasts playing particular systems will create and share utility functions that can be utilized by the wider community.<br />
<br />
The default display style for ScriptCards output is similar to the format used to document player and NPC abilities in Dungeons and Dragons 4th Edition, but does not have any system ties to D&D4E.<br />
<br />
Current OneClick Version : 1.4.0e<br />
<br />
Current Development Version : 1.4.4<br />
<br />
'''''<big>Critically Important: ScriptCards does not use/parse inline rolls. ScriptCards includes its own built-in dice roll parser to allow for the use of variables inside dice rolls. As of version 1.2.3, ScriptCards will now take inline rolls and substitute the total result value in statement strings, meaning that you can utilize inline rolls but ScriptCards will only see the result of the roll, and not parse the roll components itself.</big>'''''<br />
<br />
* {{fpl|9752053/ ScriptCards thread}}<br />
** {{fpl|10000297/ Scritpcard API Working and Sharing}}<br />
* https://github.com/kjaegers/ScriptCards/tree/main/ScriptCards_API - GitHub repository for source before the one-click version is updated.<br />
* {{yt.be|hyR7Jnq4mQM ScriptCards Intro}} 45min, Jan 2021<br />
* {{yt.be|u50xvNzS9Zk ScriptCards Magic Missile Deep Dive}} 39min, Feb 2021<br />
<br />
<br />
__TOC__<br />
=== Is ScriptCards Related to [[PowerCards]]? ===<br />
<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
Check the '''[[#What to Know if you are Coming from PowerCards|What to Know if you are Coming from PowerCards]]'''-section for a comparison table between the two scripts.<br />
<br />
== What is a ScriptCard Script ==<br />
<br />
A ScriptCard Script is text written into the chat window (either typed directly, pasted, or run via a macro) that will produce a card of information in the [[text Chat|chat window]]. A ScriptCard Script is composed of an [[API]] command: <code><nowiki>!scriptcard {{ }}</nowiki></code> enclosing any number of lines that determine the output that will be added to the card. At it simplest, the following macro:<br />
<br />
<pre>!scriptcard {{ }}</pre><br />
<br />
Will produce just a title card that displays “ScriptCards” as the name:<br />
<br />
[[File:Scriptcard blank.png]]<br />
<br />
Of course, this is just the simplest type of macro and isn’t very useful. In order to produce useful output, we need to include lines between the <code><nowiki>{{</nowiki></code> and <code><nowiki>}}</nowiki></code> that direct the API script as to what it should do.<br />
<br />
== Structure of a ScriptCard Line ==<br />
<br />
All ScriptCard lines begin with two dashes, followed by an ''statement identifier character'' that lets ScriptCards what type of line it is. There are several of these, and they are detailed in the next section. After the line type identifier, a Tag name 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.<br />
<br />
Following the Tag is a vertical bar, and then the content of the line itself. Again, each type of line might interpret this content differently.<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Identifier !! Statement Type !! Tag !! Content !! Notes<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--/</nowiki> || Comment || unused || unused || The <code>--/</code> 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--#</nowiki> || 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").<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--+</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--=</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--&</nowiki> || Assign String 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. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--@</nowiki> || 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 (i.e., [[TokenMod|!token-mod]], or [[ChatSetAttr|!setattr]], etc.)<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--:</nowiki> || 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<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--^</nowiki> || Branch To || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--></nowiki> || Call Procedure || 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<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--<</nowiki> || 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.<br />
|- <br />
| style="white-space:nowrap" | <nowiki>--?</nowiki> || Conditional Branch || Condition to be evaluated || True Branch Label<nowiki>|</nowiki>False Branch Label || The condition will be evaluated and execution will jump to one of the two indicated branches (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 included a semicolon separated list of parameters. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--s</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--l</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--v</nowiki> || 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+'''''<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--e</nowiki> || Echo to Chat || Name to send chat command as || Chat message to send || Variable substitution takes place on the tag and content.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--R</nowiki> || Retrieve Repeating Section Row information || "find", "first", or "next" || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--~</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--c</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--i</nowiki> || Information Request || User Prompt;Button Caption || InfoType;VariableName;ParameterText || See full documentation below.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--d</nowiki> || 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. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--%</nowiki> || 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. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--*</nowiki> || 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.<br />
|}<br />
<br />
== ScriptCard Statement Type Details ==<br />
The sections below detail the individual statement types supported by ScriptCards<br />
<br />
=== Comment (--/) ===<br />
<br />
A --/ statement is ignored by the ScriptCards parser. You can use this type of statement to add comments and informational text to your script. <br />
<br />
Example:<br />
<pre><br />
!script {{<br />
--/|Script Name : Fireball<br />
--/|Purpose : Allow the player to cast a fireball and blow stuff up!<br />
.<br />
.<br />
.<br />
}}<br />
</pre><br />
<br />
=== Set Parameter (--#) ===<br />
<br />
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.<br />
<br />
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.<br />
<br />
'''''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.'''''<br />
<br />
Examples:<br />
<pre><br />
--#title|Magic Missile<br />
--#leftsub|Level 1 Spell<br />
--#rightsub|Force Damage<br />
</pre><br />
<br />
The three examples above set the “title”, “leftsub”, and “rightsub” values for the card to the content value for the line. <br />
<br />
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.<br />
Settings Lines do not produce output lines on the card.<br />
<br />
The following settings are available (note that parameter names are ''not'' case sensitive):<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Name !! Effect/Use !! Default Value !! Type<br />
|-<br />
| 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<br />
|-<br />
| allowplaintextinrolls || If set to a non-zero value, plain character text in rolls will be copied to the roll text || 0 || Per-Line<br />
|-<br />
| bodyFontFace || Name of the font used in the card rows || Helvetica || Global<br />
|-<br />
| bodyFontSize || Size of the text in the card rows || 14px || Global<br />
|-<br />
| bodybackgroundimage || Specify an image (content for a CSS background-image tag) for the body area || none || Global<br />
|-<br />
| buttonBackground || Background color for buttons created with [button][/button] || #1C6EA4 || Per-Line<br />
|-<br />
| buttonBorderColor || Border (outline) color for buttons created with [button][/button] || #999999 || Per-Line<br />
|-<br />
| buttonFontFace || Font Family specifier for captions on buttons created with [button][/button] || Tahoma || Per-Line<br />
|-<br />
| buttonFontSize|| Text size for captions on buttons created with [button][/button] || x-small || Per-Line<br />
|-<br />
| buttonTextColor|| Text color of labels on buttons created with [button][/button] || #FFFFFF || Per-Line<br />
|-<br />
| 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<br />
|-<br />
| deferralcharacter || Changes the meta script deferral sequence to the specified value || ^ || Per-Line<br />
|-<br />
| diceFontColor|| Color of the dice created with the [d4] [d6], etc. formatting markers || #1C6EA4 || Per-Line<br />
|-<br />
| dicefontsize || Size of the dice created with the [d4] [d6], etc. formatting markers || 3.0em || Per-Line<br />
|-<br />
| 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<br />
|-<br />
| disablerollprocessing || If set to a non-zero value, --= lines will not process dice rolls strings || 0 || Per-Line<br />
|-<br />
| emoteBackground || Background color of the emote area || #f5f5ba || Global<br />
|-<br />
| emoteFont || Name of the font used in emote area (above the title of the output card) || Georgia || Global<br />
|-<br />
| emoteFontColor || Color of the font in the emote area || None (Empty) || Global<br />
|-<br />
| emoteFontSize || Size of the font used in the emote area || 14px || Global<br />
|-<br />
| emoteFontWeight || Font weight for the font in the emote area || bold|| Global<br />
|-<br />
| emoteState || If set to anything other than "visible", the emote portion of the card will not be displayed || visible || Global<br />
|-<br />
| emoteText || Text to display in the emote portion of the card || None (Empty) || Global<br />
|-<br />
| emotefont || Name of the font used in the emote text area || font-family: Georgia, serif; font-weight: bold; || Global<br />
|-<br />
| evenRowBackground || Hex code for the background color for even rows || #eeeeee || Per-Line<br />
|-<br />
| evenRowFontColor || Hex code for the text color for even rows || #000000 || Per-Line<br />
|-<br />
| evenrowbackgroundimage || Specify an image (content for a CSS background-image tag) for the even card rows || none || Per-Line<br />
|-<br />
| executionlimit || Maximum number of script lines the interpreter will try to execute. This prevents "infinite loop" sandbox crashes || 40000 || Global<br />
|-<br />
| hideCard || If set to any non-default value, the entire card output will be suppressed || 0 || Global<br />
|-<br />
| 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<br />
|-<br />
| 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<br />
|-<br />
| lineheight || Vertical size of each line on the output card || normal || Per-Line<br />
|-<br />
| nominmaxhighlight || If set to anything other than "0", rolls will not display crit/fumble/mixed highlight colors. || 0 || Per-Line<br />
|-<br />
| norollhighlight || If set to anything other than "0", rolls will not be formatted (plain numbers) but will still get a tooltip with details ('''''v1.3.6b+''''') || 0 || Per-Line<br />
|-<br />
| oddRowBackground || Hex code for the background color for even rows || #d0e4f5 || Per-Line <br />
|-<br />
| oddRowFontColor || Hex code for the text color for odd rows || #000000 || Per-Line<br />
|-<br />
| oddrowbackgroundimage || Specify an image (content for a CSS background-image tag) for the odd crd rows || none || Per-Line<br />
|-<br />
| reentrant || Used to name a script for rentrant button use || 0 || Global<br />
|-<br />
| 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)0 || Global<br />
|-<br />
| rollhilightlineheight || Determines the height of the hilight box placed around roll results ('''''1.4.2+''''') || 1.0em || Per-Line<br />
|-<br />
| roundUp || If set to a non-default value, integer division will round up instead of down || 0 || Per-Line<br />
|-<br />
| showfromfornonwhispers || If set to a non-zero value, will include the sender on cards that aren't whispered || 0 || Global<br />
|-<br />
| 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<br />
|-<br />
| subtitleFontColor || Color of the text in the subtitle areas || #FFFFFF || Global<br />
|-<br />
| subtitleFontFace || Name of the font used on the subtitle sections || Tahoma || Global<br />
|-<br />
| subtitleFontSize || Size of the subtitle font || 13px || Global<br />
|-<br />
| subtitleSeperator || The character(s) that will be placed between leftsub and rightsub || <nowiki>&#x2666</nowiki>; || Global<br />
|-<br />
| tableBorderRadius || CSS specifier for how rounded the borders of the output card are. Use "0px;" for square borders || 6px; || Global<br />
|-<br />
| tableShadow || CSS specifier for the drop shadow under the output card || 5px 3px 3px 0px #aaa; || Global<br />
|-<br />
| tablebgcolor || Background color of the whole card. '''''Normally not visible''''' || #EEEEEE || Global<br />
|-<br />
| tableborder || Color of the border that surrounds the whole card || 2px solid #000000; || Global<br />
|-<br />
| 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<br />
|-<br />
| timezone || IANA Specifier for the local time zone, used in system/date functions || merica/New_York || Per-Line<br />
|-<br />
| title || Text displayed in the title area of the card || ScriptCards || Global<br />
|-<br />
| titleCardBackground || A hex color code representing the background color of the title area. || #1c6ea4 || Global<br />
|-<br />
| titleFontColor || Color of the text on the card title || #FFFFFF || Global<br />
|-<br />
| titleFontFace || Name of the font used on the title area || Contrail One || Global<br />
|-<br />
| titleFontLineHeight || Line spacing on the title area || 1.2em || Global<br />
|-<br />
| titleFontSize || Size of the title font || 1.2em || Global<br />
|-<br />
| titlecardbackgroundimage || Specify an image (content for a CSS background-image tag) for the title card area || none || Global<br />
|-<br />
| titlecardbottomborder || Border CSS specifier for the bottom of the title card area || 2px solid #444444; || Global<br />
|-<br />
| titlecardgradient || If set to non-zero value, will place a vertical gradient on the title card area || 0 || Global<br />
|-<br />
| usehollowdice || If set to a non-zero value, the hollow/outline versions of the dice fonts will be used || 0 || Per-Line<br />
|-<br />
| whisper|| Comma separated list of who to whisper the output to. Use "gm" for [[GM|GMs]] and "self" for the sender || none || Global|}<br />
|}<br />
<br />
''Setting Lines do not produce output lines on the card''<br />
<br />
=== Direct Output (--+) ===<br />
<br />
A direct output line display 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.<br />
<br />
Examples of Direct Output lines:<br />
<pre><br />
--+Hello|World<br />
--+Attack|The monster rolls [$Attack] to hit!<br />
--+Damage|@{target|token_name} is hit for [$Damage] [#3333AA][b]frost[/b][/#] damage.<br />
</pre><br />
<br />
Direct Output lines support inline formatting, roll variable replacement, character attribute references, and procedure variables.<br />
<br />
=== GM Output (--*) ===<br />
<br />
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. <br />
<br />
Example:<br />
<pre><br />
--+PlayerLine|This line is shown on the public card<br />
--*GMLine|This line will only be shown to GMs, on a separate card.<br />
</pre><br />
<br />
=== Roll Variable Assignment (--=) ===<br />
<br />
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.<br />
<br />
'''''All components of a roll equation should be separated with spaces.'''''<br />
<br />
Examples:<br />
<pre><br />
--=MissileDamage|1d4 + 1<br />
--=Attack|1d20 + @{selected|strength_mod} [STR] + @{selected|pb} [PROF]<br />
</pre><br />
<br />
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. Text enclosed in square brackets ([]) is considered "flavor text" and will be added to the result text but does not impact the roll result.<br />
<br />
The following dice formats are supported:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Format Pattern !! Example !! Description<br />
|-<br />
| XdY || 3d8 || Simple format. Roll a Y-sided die X times<br />
|-<br />
| XdYkhZ || 2d20kh1 || Roll Y-sided die X times and keep the highest Z number of dice<br />
|-<br />
| XdYklZ || 4d6kl3 || Roll Y-sided die X times and keep the lowest Z number of dice <br />
|-<br />
| XdY>Z || 5d6>3 || Roll Y-sided die X times and count a 1 for each roll greater than Z <br />
|-<br />
| XdY<Z || 5d6<3 || Roll Y-sided die X times and count a 1 for each roll less than Z <br />
|}<br />
<br />
'''''Note: The dice formulae below are supported in the development version of ScriptCards and will be merged with the table above when activated on OneClick'''''<br />
::{| class="wikitable"<br />
|-<br />
! Format Pattern !! Example !! Description<br />
|-<br />
| 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<br />
|-<br />
| 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<br />
|-<br />
| 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)<br />
|-<br />
| 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<br />
|}<br />
<br />
The following operators are supported in a roll equation:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Operator !! Operation<br />
|-<br />
| + || Addition <br />
|-<br />
| - || Subtraction <br />
|-<br />
| * || Multiplication <br />
|-<br />
| / || Division <br />
|-<br />
| \ || Integer Division (Rounds down) <br />
|-<br />
| % || Modulo (Remainder of Divison)<br />
|}<br />
<br />
Roll Variables can be accessed at any time after they have been created by using the [$VariableName] format, with the following optional modifiers:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Modifier !! Meaning<br />
|-<br />
| No modifier || In a Direct Output Line (<nowiki>--+</nowiki>) 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<br />
|-<br />
| .Total || The end result of the roll equation as an unformatted number <br />
|-<br />
| .Base || The cumulative result of any dice rolled in the Roll Text (Numeric modifiers are not included) <br />
|-<br />
| .Ones || The number of dice in the roll that came up as 1s <br />
|-<br />
| .Aces || The number of dice in the roll that came up as the maximum number on the die <br />
|-<br />
| .Odds || The number of dice in the roll that came up with an odd number <br />
|-<br />
| .Evens || The number of dice in the roll that came up with an even number <br />
|-<br />
| .RollText || The raw text of the roll that was use to generate the results <br />
|-<br />
| .Text || A text representation of the results of the roll, including the numbers rolled for each die <br />
|-<br />
| .tableEntryText || The text portion of the result of a table roll<br />
|-<br />
| .tableEntryImgURL || The image source portion of the result of a table roll<br />
|-<br />
| .tableEntryValue || Numeric value of tableEntryText (via parseInt). If a non-numeric value, will be 0<br />
|-<br />
| .Raw || The total numeric result without any formatting, even if placed somewhere formatting would normally be done. <br />
|}<br />
<br />
Examples:<br />
<pre><br />
--+Total Damage|[$MissileDamage.Total] (roll was 1d4+1)<br />
--+Base Damage|[$MissileDamage.Base] (without the +1)<br />
--=Attack|1d20 + @{selected|strength_mod} [STR] + @{selected|pb} [PROF] + [$BlessBonus] [Bless]<br />
</pre><br />
<br />
In this case, 1d4 will be rolled and stored in “BlessBonus”, which can then be used in the Attack line.<br />
<br />
'''''Mathematical Functions in Roll Expressions '''''<br />
<br />
The ScriptCards roll parser works from left to right, always maintaining a current value and applying whatever comes next to the total. The following in-line functions to the roll parser. These are:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Expression !! Meaning<br />
|-<br />
| {ABS} || Absolute Value<br />
|-<br />
| {CEIL} || Ceiling value (round up to the next whole number)<br />
|-<br />
| {FLOOR} || Floor value (round down to the next whole number)<br />
|-<br />
| {ROUND} || Round value (round up if the decimal portion is greater than 0.5, otherwise round down)<br />
|-<br />
| {NEGATE} || Multiply the value by negative one.<br />
|-<br />
| {SQRT} || Take the square root of the running value. ('''''1.4.1+''''')<br />
|-<br />
| {SQUARE} || Square the running value. ('''''1.4.2+''''')<br />
|-<br />
| {CUBEROOT} || Take the cube root of the running value. ('''''1.4.2+''''')<br />
|-<br />
| {CUBE} || Cube the running value. ('''''1.4.2+''''')<br />
|-<br />
| {SIN} || Return the SIN of running value. ('''''1.4.2+''''')<br />
|-<br />
| {COS} || Return the COS of running value. ('''''1.4.2+''''')<br />
|-<br />
| {TAN} || Return the TAN of running value. ('''''1.4.2+''''')<br />
|-<br />
| {ASIN} || Return the ASIN of running value. ('''''1.4.2+''''')<br />
|-<br />
| {ACOS} || Return the ACOS of running value. ('''''1.4.2+''''')<br />
|-<br />
| {ATAN} || Return the ATAN of running value. ('''''1.4.2+''''')<br />
|}<br />
<br />
<br />
'''''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 <nowiki>[[ ]]</nowiki> 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.<br />
<br />
'''''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.<br />
<br />
'''Rolling on Rollable Tables'''<br />
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.<br />
<br />
''Roll Variable Lines do not produce output lines on the card.''<br />
<br />
=== String Variable Assignment (--&) ===<br />
<br />
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:<br />
<br />
<pre><br />
--&MyText|Hello<br />
</pre><br />
<br />
Here, we assign the text "Hello" to the string variable named MyText. You can also append text to a string variable by prefixing the content with a + sign:<br />
<br />
<pre><br />
--&MyText|+ World<br />
</pre><br />
<br />
If run after the statement above, MyText will now contain "Hello World".<br />
<br />
String variables can be referenced using the syntax [&variablename]<br />
<br />
=== Call API (--@) ===<br />
<br />
ScriptCards can use a Call API instruction to execute other API commands. The Tag contains the API 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 API command is executed.<br />
<br />
Examples:<br />
<pre><br />
--@eh|list<br />
--@alter|_target|@{target|token_id} _bar|3 _amount|-[$Damage]<br />
</pre><br />
<br />
In the first example above, the command <code>!eh list</code> will be executed, calling [[EncounterHelper]]. In the second, {{fpl|1216260/ AlterBars}} is called to modify a token's Bar 3 value.<br />
<br />
'''''Note:''''' When ScriptCards (or any API script) runs other API 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).<br />
<br />
See [[API:Script Index]] for more options.<br />
<br />
=== Branch Label (--:) ===<br />
<br />
A branch label defines a line in your code that can be reached by one of the branching instructions (<nowiki>--^</nowiki>, <nowiki>--></nowiki>, or <nowiki>--?</nowiki>). The Tag serves as the label name, and must be unique on the card.<br />
<br />
The vertical bar (|) separator must be present, but the content portion of the line is unused and can be treated as a comment.<br />
<br />
Examples:<br />
<pre><br />
--:MyLoop|<br />
--:CriticalHit|Will jump here if we roll a critical hit!<br />
</pre><br />
<br />
''A Branch Label line does not produce an output line on the card.''<br />
<br />
=== Branch (--^) === <br />
<br />
A Branch line 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.<br />
<br />
Examples:<br />
<pre><br />
--^MyLoop|Jumps to MyLoop<br />
--^SkipCrit|We didn't crit, so skip the Crit code<br />
</pre><br />
<br />
''A Branch line does not produce an output line on the card.''<br />
<br />
=== Call Procedure (-->) ===<br />
<br />
Similar to a branch, a Call Procedure (sometimes knows 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 (<nowiki>--<</nowiki>) 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 (;).<br />
<br />
Examples:<br />
<pre><br />
-->FixFormat|#3333FF;#999999<br />
</pre><br />
<br />
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%].<br />
<br />
=== Return (--<) ===<br />
<br />
A return instruction marks the end of a Gosub procedure. 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.<br />
<br />
Examples:<br />
<pre><br />
--<|<br />
--<|End of MySub<br />
</pre><br />
<br />
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.<br />
<br />
=== Conditional Statement (--?) ===<br />
<br />
A conditional statement contains some equation in the Tag that will be evaluated. '''''If any part of the comparison can/does contain a space, it needs to be surrounded by double quotes'''''<br />
<br />
Based on the true/false result of the evaluation, one of two execution paths will be taken. These execution paths are detailed in the content section of the statement. The "if true" path is specified first (directly after the vertical bar), and the "if false" path is specified after it, also separated by a vertical bar.<br />
<br />
Example:<br />
<pre><br />
--?[$AttackRoll.Total] -ge [$TargetAC]|Hit|Miss<br />
</pre><br />
<br />
'''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.'''<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Branch Format !! Meaning<br />
|-<br />
| Label || If just a label is specified, execution will branch to that label when the comparison is matched.<br />
|-<br />
| >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 <br />
|-<br />
| =VariableName || The roll variable "VariableName" will be assigned the value following a semicolon (ex: --?1 -eq 1|=Roll;1d20)<br />
|-<br />
| &VariableName || The string variable "VariableName" will be assigned the value following a semicolon (ex: --?1 -eq 1|&Result;Hit|&Result;Miss)<br />
|-<br />
| % or %! || The current for...next loop will perform the "next" action (%) or will break out (%!) <br />
|-<br />
| [ || Code block (see below)<br />
|}<br />
<br />
Examples:<br />
<pre><br />
--?[$AttackRoll.Base] -eq 20|CriticalHit<br />
--?[$AttackRoll.Base] -eq 1|>Fumble;@{selected|dexterity_mod}<br />
--?"@{target|npc_type}" -inc "undead"|&MonsterType;Undead|&MonsterType;Not Undead<br />
--?[$Attack.Total] >= [$ArmorClass]|>Hit|>Miss<br />
</pre><br />
<br />
In the first example, if the Base value of AttackRoll is a 20 (natural 20 on the die) execution will branch to the CriticalHit label.<br />
<br />
In the second example, 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%].<br />
<br />
The third example looks for the word "undead" in the npc_type attribute of the targeted character. If it exists in the text, the MonsterType string variable will be set to "Undead", otherwise it will be set to "Not Undead". <br />
<br />
The final example would call 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.<br />
<br />
''Text that does/may contain a space should be enclosed in double quotes.''<br />
<br />
The following comparison operators are available:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Comparator !! Meaning<br />
|-<br />
| -eq || Equal To <br />
|-<br />
| -eqi || Case insensitive Equal To <br />
|-<br />
| -ne || Not Equal To <br />
|-<br />
| -nei || Case insensitive Not Equal To <br />
|-<br />
| -gt || Greater Than <br />
|-<br />
| -ge || Greater Than or Equal To <br />
|-<br />
| -lt || Less Than <br />
|-<br />
| -le || Less Than or Equal To <br />
|-<br />
| -inc || Includes (text strings). <br />
|-<br />
| -ninc || Does Not Include (text strings). <br />
|}<br />
<br />
Multi-part conditionals are supported with -and and -or as separators. For example:<br />
<br />
<pre><br />
--?[$Attack.Total] -ge @{target|npc_ac} -and [$Attack.Base] -ne 20|HitButNotCrit<br />
</pre><br />
<br />
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):<br />
<br />
true AND false OR true<br />
<br />
Will be evaluated as true. The first two (true and false) will be false, but then false OR true will be true.<br />
<br />
Conversely:<br />
<br />
true or false and false<br />
<br />
Will be false, because the first true and false will evaluate to true, and then true and false will be false.<br />
<br />
'''CODE BLOCKS'''<br />
<br />
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.<br />
<br />
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:<br />
<br />
<pre><br />
!script {{<br />
--=Roll|1d2<br />
--+Roll|[$Roll]<br />
--?[$Roll.Total] -eq 2|[<br />
--&Value|Yep!<br />
--+|We are inside the TRUE portion of the block<br />
--]|[<br />
--&Value|Nope<br />
--+|We are inside the FALSE portion of the block<br />
--]|<br />
--+After|the blocks!<br />
--+Value|[&Value]<br />
}}<br />
</pre><br />
<br />
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 --]|. <br />
<br />
At this time, blocks cannot be nested, and can only be created as part of a conditional (--[ is not a valid statement type)<br />
<br />
''A conditional statement does not produce a line of output on the card.''<br />
<br />
=== Case Statement (--c) ===<br />
<br />
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 (:). Each match condition includes a branch label that will be used if the test value matches the item. 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:<br />
<br />
<pre><br />
!script {{<br />
--#title|Case Statement Testing<br />
--=Roll|1d4<br />
--C[$Roll.Total]|1:>One;[$Roll]|2:>Two;[$Roll]|3:>Three;[$Roll]|4:>Four;[$Roll]<br />
--X|<br />
<br />
--:One| --+Value|was One ([%1%]) --<|<br />
--:Two| --+Value|was Two ([%1%]) --<|<br />
--:Three| --+Value|was Three ([%1%]) --<|<br />
--:Four| --+Value|was Four ([%1%]) --<|<br />
}}<br />
</pre><br />
<br />
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 variable as a parameter.<br />
<br />
=== Save and Load (--s and --l) ===<br />
<br />
This statement pair is used to either store (--s) or load (--l) data from persistent storage. Items stored in persistent storage remain between card rolls and between Roll20 sessions. There are two types of data that can be stored: settings and roll variables. <br />
<br />
Examples:<br />
<br />
<pre><br />
--Ssettings|GreenStyle<br />
--Srollvariables|FirstCardVars<br />
</pre><br />
<br />
In this case, the tag for the statement determines what type of item is being saved (settings or rollvariables). When saving settings, all non-default settings are written to the named setting storage value. When Roll Variables are saved, all variables that currently exist will be saved to the named storage value.<br />
<br />
Loading stored items simply requires the same command with the --l statement type:<br />
<br />
<pre><br />
--Lsettings|GreenStyle<br />
--Lrollvariables|FirstCardVars<br />
</pre><br />
<br />
When loading settings, all stored settings will be applied to the current card settings. You can override settings by changing them after the load.<br />
<br />
When loading roll variables, the saved variables will be added to (or overwrite if they have the same name) any variables on the current card. This means it is safe to create roll variables before the load statement.<br />
<br />
'''Practical Uses'''<br />
The major intended use of persistent storage is for storing card formats for use in later scripts. For example, the following script:<br />
<br />
<pre><br />
!scriptcard {{<br />
--#titlecardbackground|#22CC22<br />
--#oddrowbackground|#cceecc<br />
--#evenrowbackground|#99ee99<br />
--Ssettings|@{selected|token_name}<br />
}}<br />
</pre><br />
<br />
Would save the titlecardbackground, oddrowbackground, and evenrowbackground settings to a saved list named after the selected token's name. When creating cards for that token to run later, you could include the line:<br />
<br />
<pre><br />
--Lsettings|@{selected|token_name}<br />
</pre><br />
<br />
To load all of the settings at once. By creating these setting sets for each character, you can specify a different color scheme for each character that can then be used in cards with a single formatting line.<br />
<br />
There is a supplemental ! command added to support saved settings:<br />
<br />
<pre><br />
!sc-liststoredsettings<br />
</pre><br />
<br />
Will produce a list of all stored setting names, with buttons to list the setting values stored in each group and a button to delete groups as needed.<br />
<br />
=== Visual Effects (--v) ===<br />
<br />
The --v statement can be used to create visual effects on the tabletop. The tag portion of the statement can be either "token" or "betweentokens". The content portion of the statement contains the required parameters for the effect generation, separated by spaces. If the effect is "none", no effect will be played. If any other value that doesn't match a Roll20 effect name will result in a burst-fire effect.<br />
<br />
For "token" effects, the parameters are the token id for the token the effect happens on, followed by the effect specifier.<br />
<br />
Example:<br />
<pre><br />
--vtoken|@{selected|token_id} burst-fire<br />
</pre><br />
<br />
For "betweentoken" effects, the parameters are the source token id, the target token id, and the effect specifier.<br />
<br />
Example:<br />
<pre><br />
--vbetweentokens|@{selected|token_id} @{target|token_id} beam-magic<br />
</pre><br />
<br />
'''''Version 1.2.8+'''''<br />
<br />
An additional effect specifier, "point" is available in 1.2.8+. This specifier allows you to create a visual effect at a designated X/Y pixel coordinate. Future updates will add custom-vfx support to this option. The parameters are the X and Y coordinates and the effect descriptor. As of version 1.2.9, you can also use custom effect specifiers with Point effects:<br />
<br />
<pre><br />
--vpoint|150 200 burst-fire<br />
</pre><br />
<br />
=== Echo to Chat (--e) ===<br />
<br />
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.<br />
<br />
Example:<br />
<pre><br />
--eThe Ghost|/em hovers around @{selected|character_name}... BOO!<br />
</pre><br />
<br />
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).<br />
<br />
'''''Whispering'''''<br />
<br />
You can use the echo statement to send a whisper, but there's a trick to it. If you execute this code here:<br />
<br />
<pre><br />
--eThe Ghost|/w ExamplePlayerName Boo.<br />
</pre><br />
<br />
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.<br />
<br />
So, in conclusion, it's best to use something like this when you're sending a whisper:<br />
<br />
<pre><br />
!script {{<br />
--#hidecard|1<br />
--&sender|The Ghost<br />
--&receiver|ExamplePlayerName<br />
--&message|Boo.<br />
--e[&sender]|/w [&receiver] [&message]<br />
--eScriptCards|/w gm **Whispered from [&sender] to [&receiver]:** [&message] <br />
}}<br />
</pre><br />
<br />
This will ensure that the message appears in your chat feed as well.<br />
<br />
=== Repeating Section Access (--R) ===<br />
<br />
ScriptCards (as of v0.0.13) supports accessing repeating section rows on a character sheet (for example: the attacks, the items, and the repeating resources) with the --R statement type. <br />
<br />
There are three basic commands you can use with --R, and they are specified by the tag used:<br />
<br />
'''''The "find" tag'''''<br />
<br />
An Rfind statement is used to search through a repeating field. Here is the general form of such a statement.<br />
<br />
<pre><br />
--Rfind|characterid;EntryName;SectionPrefix;SearchField<br />
</pre><br />
<br />
This is the most direct way to access a repeating section row. Supplying the character ID, followed by what you are looking for (Greatsword, for example), followed by the character sheet's section prefix (repeating_attack), followed by the field to check what you are searching for (atkname) will load the matching section (if found) into the script parsers memory. For example:<br />
<br />
<pre><br />
--Rfind|@{selected|character_id};Greatsword;repeating_attack;atkname<br />
</pre><br />
<br />
Will look at the character's "repeating_attack" section for an entry with an atkname value equal to "Greatsword". Similarly:<br />
<br />
<pre><br />
--Rfind|@{selected|character_id};Bite;repeating_npcaction;name<br />
</pre><br />
<br />
Will look for a "Bite" action on an NPC's action list.<br />
<br />
'''''The "first" tag'''''<br />
<br />
<pre><br />
--Rfirst|characterid;section prefix<br />
</pre><br />
<br />
This form of the --R command will look at all of the entries in the specified repeating section and load the first one into memory:<br />
<br />
<pre><br />
--Rfirst|@{selected|character_id};repeating_attack<br />
</pre><br />
<br />
Would load the character's first "repeating_attack" row into memory.<br />
<br />
'''''The "next" tag'''''<br />
<br />
<pre><br />
--Rnext|<br />
</pre><br />
<br />
No parameters are required for --Rnext, which loads the next entry in the list that was obtained with "first" into memory.<br />
<br />
'''''The section prefixes for the 5E by roll20 character sheet'''''<br />
<br />
Can somebody please add a list of them here?<br />
<br />
'''''Additional information'''''<br />
<br />
However a row is obtained, it will be parsed to replace any attribute references (ie, @{level}) with the corresponding character attribute.<br />
<br />
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".<br />
<br />
You can reference repeating attribute data using the syntax [*R:attributename] syntax (similar to referencing standard character attributes).<br />
<br />
Here are some examples:<br />
<br />
Display the details of the "Greatsword" PC attack:<br />
<br />
<pre><br />
!script {{<br />
--Rfind|@{selected|character_id};Greatsword;repeating_attack;atkname<br />
--+Attack Name|[*R:atkname]<br />
--+Base Damage|[*R:dmgbase]<br />
}}<br />
</pre><br />
<br />
[[File:Scriptcards repeating greatsword.png|Repeating Greatsword Attack]]<br />
<br />
List all of the actions an NPC can take (just actions, not legendary, etc.)<br />
<br />
<pre><br />
!script {{<br />
--#title|NPC Actions<br />
--#leftsub|@{selected|token_name}<br />
--Rfirst|@{selected|character_id};repeating_npcaction<br />
--:DisplayLoop|<br />
--?"[*R:name]" -eq NoRepeatingAttributeLoaded|Done<br />
--+Action:|[*R:name] [*R:attack_damage] [*R:attack_damagetype]<br />
--?"[*R:attack_damage2]" -eq ""|NoSecondaryDamage<br />
--+ |[*R:attack_damage2] [*R:attack_damagetype2]<br />
--:NoSecondaryDamage|<br />
--Rnext|<br />
-->DisplayLoop| <br />
--:Done|<br />
}}<br />
</pre><br />
<br />
[[File:Scriptcards repeating npcactions.png]]<br />
<br />
In the script above, we get the "first" repeating_npcaction and display information about it. We then execute "next" and repeat until we run into "NoRepeatingAttributeLoaded".<br />
<br />
'''''Special debugging command: dump'''''<br />
<pre><br />
--Rdump|<br />
</pre><br />
<br />
The "dump" command will list all of the attributes ScriptCards knows about for the currently loaded repeating row to the API Console Log.<br />
<br />
=== Assign Variable to Built-In Function (--~) ===<br />
<br />
ScriptCards has the ability to run a function built into the API script and return the results to a variable. Some functions return roll variables, while others return strings. See the function table below for details. The format is:<br />
<br />
--~VariableName|function;param1;param2;param3;...<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Function Name !! Parameters !! Description<br />
|-<br />
| distance || token_A_ID;token_B_ID || Calculate the Chebyshev distance in grid units between two tokens. This is the measurement scheme D&D 4E/5E use for diagonal distance measurement<br />
|-<br />
| euclideandistance || token_A_ID;token_B_ID || Calculate the Euclidean distance between two tokens. This is essentially the Pythagorean theorem in action. Returns the result in grid units.<br />
|-<br />
| euclideanpixel || token_A_ID;token_B_ID || Calculate the Euclidean distance between two tokens and returns the result is pixels instead of grid units. <br />
|-<br />
| euclideanlong || token_A_ID;token_B_ID || 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 is calculated instead of before. More accurate over long distances. <br />
|-<br />
| manhattandistance || token_A_ID;token_B_ID || Also called "taxicabdistance" (which is an acceptable function name), this measures to how-many-over, how-many-up/down distance, disallowing diagonal movement.<br />
|-<br />
| getselected || none || 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 the first selected token, VariableName2 the second, etc.<br />
|}<br />
<br />
'''''Functions with Sub Functions'''''<br />
<br />
Most ScriptCards functions are grouped into set as sub functions. The table below lists the major functions and their sub functions.<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Function Name !! Sub Function !! Parameters !! Return Type !! Description<br />
|-<br />
| array || define || arrayname;value1;value2;... || none || Creates an array called "arrayname" and adds value1, value2, etc. to the array<br />
|-<br />
| array || sort || arrayname || none || Sorts the specified array in place in ascending order<br />
|-<br />
| array || add || arrayname;value1;value2;... || none || Adds value1, value2, ... to the existing array "arrayname"<br />
|-<br />
| array || remove || arrayname;value1;value2;... || none || Removes value1, value2, ... from the existing array "arrayname". Resets the array index to 0.<br />
|-<br />
| array || replace || arrayname;currentvalue;newvalue || none || Replaces all occurrences of "currentvalue" in "arayname" with "newvalue"<br />
|-<br />
| array || setatindex || arrayname;index;newvalue || none || Replaces the array item at index "index" with "newvalue"<br />
|-<br />
| array || getindex || arrayname || stringVariable || Retrieves the current index in "arrayname" and stores it in the supplied string variable<br />
|-<br />
| array || setindex || arrayname;newindex || none || Sets the current index in array "arrayname" to "newindex"<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| array || removeat || arrayname;indexposition || none || Removes the item at index "indexposition" from "arrayname". Resets the current array index to 0.<br />
|-<br />
| array || indexof || arrayname;searchvalue || stringVariable || Searches the array "arrayname" for and item with the value of "searchvalue" and, if found, returns the index of the first matching value or "ArrayError" if not found<br />
|-<br />
| array || getlength || arrayname || stringVariable || Returns the number of items in array "arrayname"<br />
|-<br />
| array || pagetokens || arrayname;tokenid;(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. 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.)<br />
|-<br />
| 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.<br />
|-<br />
| array || stringify || arrayname || stringVariable || Returns all of the items in "arrayname" as a string separated by semicolons (;)<br />
|-<br />
| array || fromstring || arrayname || delimiter;string || Creates an array from "string", splitting "string" on "delimiter" to separate the items<br />
|-<br />
| array || statusmarkers|| arrayname;tokenid || none|| Creates an array (arrayname) of the active statusmarkers (sometimes called Token Markers) for the specified tokenid<br />
|-<br />
| math || angle || math;angle;tokenid;tokenid|| rollVariable || Calculates the angle between two tokens and returns the value in degrees<br />
|-<br />
| math || ceil || math;ceil;value || rollVariable || Rounds '''value''' up to the next integer, dropping any decimal portion of the number<br />
|-<br />
| math || clamp || math;clamp;value;lowerBound;upperBound || rollVariable || Returns '''value''', but restricted to the range of '''loweBound''' and '''upperBound'''.<br />
|-<br />
| math || floor || math;floor;value || rollVariable || Rounds '''value''' down, dropping any decimal portion of the number<br />
|-<br />
| math || max || math;max;valueA;valueB || rollVariable || Returns the larger of '''valueA''' vs '''valueB'''<br />
|-<br />
| math || min || math;min;valueA;valueB || rollVariable || Returns the smaller of '''valueA''' vs '''valueB'''<br />
|-<br />
| math || round || math;round;value || rollVariable || Rounds '''value''' to the nearest integer<br />
|-<br />
| string || length || string;length;stringValue || rollVariable || Returns the length of '''stringValue''' in characters<br />
|-<br />
| string || before || string;before;searchText;stringValue || stringVariable || Searches '''stringValue''' for '''searchText''' and returns the portion of '''stringValue''' prior to that text<br />
|-<br />
| string || after || string;after;searchText;stringValue || stringVariable || Searches '''stringValue''' for '''searchText''' and returns the portion of '''stringValue''' after that text<br />
|-<br />
| string || left || string;left;count;stringValue || stringVariable || Returns the leftmost '''count''' characters of '''stringValue'''<br />
|-<br />
| string || right || string;right;count;stringValue || stringVariable || Returns the rightmost '''count''' characters of '''stringValue'''<br />
|-<br />
| string || replace || string;replace;searchText;replaceText;stringValue || stringVariable || Replaces '''searchText''' in '''stringValue''' with '''replaceText''' and returns the resulting string<br />
|-<br />
| string || replaceall || string;replace;searchText;replaceText;stringValue || stringVariable || Replaces all intances of '''searchText''' in '''stringValue''' with '''replaceText''' and returns the resulting string '''''Requires 1.2.9+'''''<br />
|-<br />
| string || trim || string;trim;stringValue || stringVariable || Removes leading and trailing spaces from stringValue and returns the result. <br />
|-<br />
| string || substring || string;substring;start;count;stringValue || stringVariable || Returns '''count''' characters starting at '''start''' from '''stringValue'''<br />
|-<br />
| 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.<br />
|-<br />
| string || tolowercase || string;tolowercase;stringValue || stringVariable || Converts the passed string to lower case and assigns to the passed variable name. <br />
|-<br />
| string || touppercase || string || stringVariable || Converts the passed string to upper case and assigns to the passed variable name. <br />
|-<br />
| 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. <br />
|-<br />
| 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.<br />
|-<br />
| 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'''.<br />
|-<br />
| turnorder || clear || none || none || Clears all entries from the {{Turn Tracker}}/Initiative<br />
|-<br />
| turnorder || addtoken || tokenid;trackervalue || none || Adds the token represented by "tokenid" to the initiative tracker with an initiavie value of "trackervalue"<br />
|-<br />
| turnorder || replacetoken || tokenid;trackervalue || none || Replaces the token represented by "tokenid" in the initiative tracker with an initiavie value of "trackervalue". Will add the token if it doesn't exist in the tracker.<br />
|-<br />
| turnorder || removetoken || tokenid || none || Removes the token represented by "tokenid" from the initiative tracker if it exists<br />
|-<br />
| turnorder || addcustom || textlabel;trackervalue || none || Add a custom text entry to the {{Turn Tracker}}/Initiative named "textlabel" with an initiative value of "trackervalue"<br />
|-<br />
| system || date || getdatetime || stringVariable || Returns the date time in the active timezone (see settings) <br />
|-<br />
| system || date || getdate || stringVariable || Returns the date in the active timezone (see settings) <br />
|-<br />
| system || date || gettime || stringVariable || Returns the time in the active timezone (see settings)<br />
|-<br />
| system || dumpvariables || "rolls", "string", or "array" || none || Dumps all of the defined variables of the indicated type to the console log<br />
|-<br />
| system || findability || system;findability;charactername;abilityname || stringVariable || Returns the object ID of the ability on the indicated character or "AbilityNotFound"<br />
|-<br />
|}<br />
<br />
Examples:<br />
<br />
<pre><br />
--~HowFarAway|distance;@{selected|token_id};@{target|token_id}<br />
</pre><br />
<br />
Returns the distance (Chebyshev) between the selected and target tokens and stores it in "HowFarAway".<br />
<br />
<pre><br />
--SelectedDudes|getselected<br />
</pre><br />
<br />
If 5 tokens were selected, 6 variables would be created: SelectedDudesCount (with a value of 5), SelectedDudes1, SelectedDudes2, SelectedDudes3, SelectedDudes4, SelectedDudes5.<br />
<br />
=== Information Request (--i) ===<br />
<br />
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.<br />
<br />
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.<br />
<br />
After the user has clicked the button and responded to the requests, ScriptCards will resume processing the script from where it left off.<br />
<br />
Here is an example “i” line:<br />
<br />
<pre><br />
--IScriptCards needs additional information to continue;Click to select a target and provide information|t;MyNewTarget;Missile1Target||q;MyNameIs;What is your name?<br />
</pre><br />
<br />
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.<br />
<br />
Supported information request types are “t” for target token, and “q” for query.<br />
<br />
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).<br />
<br />
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:<br />
<br />
<pre><br />
q;UserName;What is your name?|Fred|Bob|Sally|Nancy<br />
</pre><br />
<br />
Would have a dropdown menu with four choices.<br />
<br />
== Inline Formatting ==<br />
<br />
Inline formatting is processed on Direct Output lines only (--+ lines) and the following inline format markup is available:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Formatting Tags !! Description<br />
|-<br />
| [b]..[/b] || Bold the text between the markers <br />
|-<br />
| [i]..[/i] || Italicize the text between the markers <br />
|-<br />
| [u]..[/u] || Underline the text between the markers <br />
|-<br />
| [s]..[/s] || Strike-Thru the text between the markers <br />
|-<br />
| [c]..[/c] || Center alignment <br />
|-<br />
| [l]..[/l] || Left alignment <br />
|-<br />
| [r]..[/r] || Right alignment <br />
|-<br />
| [j]..[/j] || Full justification alignment <br />
|-<br />
| [#xxx]..[/#] or [#xxxxxx]..[/#] || Use a 3 or 6 digit hex code to colorize the text between the markers <br />
|-<br />
| [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, <code>[img width=128 height=128]</code> )<br />
|-<br />
| [button]caption::action[/button] || Create a button with the label "caption" that performs the action defined by "action". <br />
|-<br />
| [t] || Converted to HTML table tag. Text after the "t" will be included inside the tag (width, border, etc)<br />
|-<br />
| [/t] || Converted to HTML close table tag.<br />
|-<br />
| [tr] || Converted to HTML table row tag. Text after the "tr" will be included inside the tag<br />
|-<br />
| [/tr] || Converted to HTML close table row tag.<br />
|-<br />
| [td] || Converted to HTML table cell tag. Text after the "tr" will be included inside the tag<br />
|-<br />
| [/td] || Converted to HTML close table cell tag.<br />
|}<br />
<br />
== Variables ==<br />
<br />
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. While it is possible to assign both a string and a roll variable the same name, doing so will likely result in confusion when looking at the script later, so it is not recommended.<br />
<br />
String Variables are assigned with the --& statement and are referenced using [&variableName] notation.<br />
<br />
Roll Variables are assigned with the --= statement, and the assignment value is always processed by the ScriptCards Roll Processor (resolves dice rolls, etc.)<br />
<br />
There are a handful of variables assigned automatically when a ScriptCard is executed. These are all string variables, and are:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Variable !! Value<br />
|-<br />
| SendingPlayerID || Contains the object ID of the player that sent the macro<br />
|-<br />
| SendingPlayerName || Contains the display name of the player<br />
|-<br />
| SendingPlayerColor || Contains the color code associated with the player<br />
|-<br />
| SendingPlayerSpeakingAs || The contents of the "Speaking As" dropdown window<br />
|-<br />
| SendingPlayerIsGM || Contains 1 if the player is a GM, and 0 if the player is NOT a GM<br />
|}<br />
<br />
== Arrays ==<br />
<br />
Arrays are a special type of variable, and are managed by the function (<nowiki>--~</nowiki> command). All of the array function commands follow the same pattern:<br />
<br />
<pre>--~variableName|array;subcommand;arrayname;param1;param2;param3;...</pre><br />
<br />
Not all array commands return anything to "variableName". The function table above will specify the return type of the command if any.<br />
<br />
There are a couple of different ways to create an array:<br />
<br />
The '''define''' array subcommand creates (or recreates) an array and assigns it values - one for each included parameter after the array name. For example:<br />
<br />
<pre>--~|array;define;Fruits;mango;peach;strawberry;apricot;banana;apple</pre><br />
<br />
will create an array called '''Fruits''' with 6 elements in the order listed in the command (mango, peach, etc.)<br />
<br />
You can also use two other subcommands to create arrays based on tokens:<br />
<br />
<pre>--~Count|array;pagetokens;Everybondy;@{selected|token_id}</pre><br />
<br />
and<br />
<br />
<pre>--~Count|array;selectedtokens;Selected</pre><br />
<br />
In both cases, arrays of tokens will be created, and a string variable called "Count" will be set to the number of tokens in the array. The '''pagetokens''' command returns (by default) all of the tokens on the page that contains the token passed as the parameter after the array name. You can filter the tokens that "pagetokens" includes in the array by appending an optional parameter describing the type of token you are looking for:<br />
<br />
<pre>--~Count|array;pagetokens;Everybondy;@{selected|token_id};npc</pre><br />
<br />
Will return only tokens on the page that represent characters that do not have a ''controlledby'' parameter set. The available options are "all" (default), "char", "graphic", "pc", and "npc".<br />
<br />
The '''selectedtokens''' command returns an array with all of the tokens that were selected when the script was called.<br />
<br />
You can also use an arbitrary string to create an array, specifying a delimiter with the '''fromstring''' command:<br />
<br />
<pre><br />
--&names|Fred<br />
--&names|+,Sally<br />
--&names|+,Ted<br />
--&names|+,Joyce<br />
--~|array;fromstring;,;[&names]<br />
</pre><br />
<br />
The above example builds a comma-separated string and then uses "fromstring" to create an array with 4 elements from it, specifying the comma as the delimiter.<br />
<br />
Finally, you can use the '''statusmarkers''' command to create an array with one entry for each active status marker on a specified token:<br />
<br />
<pre>--~|array;statusmarkers;Conditions;@{selected|token_id}</pre><br />
<br />
will create an array with one entry for each status active on the selected token. The array elements will be the internal name of the status (if you are using custom status marker packs, the names will be specified in the marker pack).<br />
<br />
'''Traversing Arrays'''<br />
<br />
Each array keeps track of an internal index position (starting at 0). Several commands let you manage this index:<br />
<br />
*'''getindex''' returns the current index value<br />
*'''setindex''' sets the index to the specified location in the array<br />
*'''getlength''' returns the number of elements in the array<br />
*'''indexof''' returns the index location of the specified element<br />
<br />
Other commands let you retrieve values from the array:<br />
<br />
*'''getfirst''' sets the index to 0 and returns the value at that position<br />
*'''getnext''' advances the index by 1 and returns the new current value<br />
*'''getprevious''' reduces the index by 1 and returns the new current value<br />
*'''getlast''' sets the index to the last elements in the array and returns the new current value<br />
<br />
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.<br />
<br />
'''Manipulating Array Elements'''<br />
<br />
Several array commands deal with inserting, removing, and modifying elements:<br />
<br />
*'''add''' works just like define, except that it takes an existing array and adds elements to it based on the passed parameters<br />
*'''remove''' looks for items matching each passed parameter and removes them from the indicated array if they exist<br />
*'''removeat''' allows you to specify an index location in the array and remove the element at that position<br />
*'''replace''' searches an array for a value and replaces all occurrences of it with a new value (if found)<br />
*'''sort''' sorts the elements in the array in ascending order<br />
*'''strinfigy''' returns a string variable that includes each array element separated by semicolons (;) <br />
<br />
'''Referencing Array Elements'''<br />
<br />
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.<br />
<br />
<pre><br />
!script {{<br />
--~dummy|array;pagetokens;myarray;@{selected|token_id}<br />
--~count|array;getcount;myarray<br />
--+Total:|There are [&count] graphical objects on the page<br />
--~testvar|array;getfirst;myarray<br />
--:loop|<br />
--+Value|[*[&testvar]:character_name]<br />
--~testvar|array;getnext;myarray<br />
--?[&testvar] -ne ArrayError|loop<br />
--+Loop1|Is Done!<br />
}}<br />
</pre><br />
<br />
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:<br />
<br />
<pre><br />
!script {{<br />
--~dummy|array;pagetokens;myarray;@{selected|token_id}<br />
--~count|array;getcount;myarray<br />
--+Total:|There are [&count] graphical objects on the page<br />
--%loopCounter|1;[&count]<br />
--+Value|[*[@myarray([&loopCounter])]:character_name]<br />
--%|<br />
--+Loop|Is Done!<br />
}}<br />
</pre><br />
<br />
This line : <nowiki>--+Value|[*[@myarray([&loopCounter])]:character_name]</nowiki> uses [@arrayName(index)] format (inside a [*characterid:attribute] syntax) to perform the same task as running through the loop with the index.<br />
<br />
(Note: Additional examples are on the way...)<br />
<br />
== For...Next Loops ==<br />
<br />
For...Next loops in ScriptCards are supported with the with the --% statement type. A loop is defined by starting off with:<br />
<br />
<pre><br />
--%LoopCounter|<start>;<end>;[step]<br />
</pre><br />
<br />
The start and end values are required, while the step parameter is optional. If the step is omitted, it will be assumed to be 1. A string variable named after the line tag ("LoopCounter" in the case above) will be created and will hold the current iteration value for the loop. Here is a real example:<br />
<br />
<pre><br />
--%LoopCounter|1;10;1<br />
</pre><br />
<br />
This will begin a loop identified by "LoopCounter" that will start at 1, increasing by 1 each iteration (the step) until it has completed 10 executions.<br />
<br />
The "next" statement is simply <code>--%|</code>, with no tag or parameters. This indicates to ScriptCards that it should increment the counter and go back to the beginning of the loop. Extending the example above:<br />
<br />
<pre><br />
!script {{<br />
--%LoopCounter|1;10;1<br />
--=Roll|1d20<br />
--+Loop|Counter is [&LoopCounter], roll was [$Roll]<br />
--%|<br />
}}<br />
</pre><br />
<br />
The <code>--%!|</code> sequence will break out of the loop, no matter how many iterations are remaining.<br />
<br />
The % and %! character sequences can also be used as part of a 1.2.1+ non-branching conditional to continue or break the loop:<br />
<br />
<pre><br />
--?"X[&RollInto]X" -eq "XX"|%<br />
</pre><br />
<br />
In this example, if the string variable RollInfo is empty, the loop will return to the top and continue with the next iteration, while:<br />
<br />
<pre><br />
--?"X[&RollInto]X" -eq "XX"|%!<br />
</pre><br />
<br />
Would cause the whole loop to end if the condition were true.<br />
<br />
== Referencing ==<br />
<br />
=== Roll Variables===<br />
<br />
Roll Variables can be referenced from the content portion of any line type, and from the tag portion of conditional statements. The referenced value is replaced when the line is executed.<br />
<br />
There are several modifiers that can be used to reference parts of a roll:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Modifier !! Meaning<br />
|-<br />
| No modifier || In a Direct Output Line (<nowiki>--+</nowiki>), GM Output Line (<nowiki>--*</nowiki>), or String Assignement (<nowiki>--&</nowiki>), 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<br />
|-<br />
| .Total || The end result of the roll equation. Formatting rules for "No Modifier" apply based on line type. <br />
|-<br />
| .Raw || The total value of the roll variable without any formatting, no matter what kind of line the reference is used in.<br />
|-<br />
| .Base || The cumulative result of any dice rolled in the Roll Text (Numeric modifiers are not included) <br />
|-<br />
| .Ones || The number of dice in the roll that came up as 1s <br />
|-<br />
| .Aces || The number of dice in the roll that came up as the maximum number on the die <br />
|-<br />
| .Odds || The number of dice in the roll that came up with an odd number <br />
|-<br />
| .Evens || The number of dice in the roll that came up with an even number <br />
|-<br />
| .RollText || The raw text of the roll that was use to generate the results <br />
|-<br />
| .Text || A text representation of the results of the roll, including the numbers rolled for each die <br />
|-<br />
| .tableEntryText || The text portion of the result of a table roll<br />
|-<br />
| .tableEntryImgURL || The image source portion of the result of a table roll<br />
|-<br />
| .tableEntryValue || If the tableEntryText is purely numeric, will contain the numeric value<br />
|}<br />
<br />
=== String Variables ===<br />
<br />
To reference a string variable, use the notation [&variablename]. String variables can be referenced in direct output, roll variable assignment, and string variable assignment statements.<br />
<br />
=== Character/Token Attributes ===<br />
<br />
A character or token attribute can be referenced from content portion of any type of line and is substituted when the line is executed. The general format for referencing a character attribute is [*ID:attribute]. ID can be a token ID or a character ID (these start with a dash). Additionally if you have specified a sourceToken or targetToken, you can substitute "S" or "T" for the ID (for example [*S:npc_type] will retrieve the npc_type attribute from the source token.<br />
<br />
By default, all attribute references will be pulled from the '''''character''''' object that the ID represents (either directly or by being a Token ID that represents a character).<br />
<br />
Keep in mind, that if you want to access the "max" of a character attribute (for example, the max hit points), then you cannot trust the name that your roll20 character sheet shows you when you hover your mouse over the max hit points. For example, this reference will not work: [*S:hp_max]. Instead, you need to use this reference: [*S:hp^].<br />
<br />
If your ID refers to a token, token attributes can be accessed by preceding the attribute name with "t-", for example [*S:t-aura1_radius]. Supported token attributes are:<br />
<br />
{|<br />
| t-name || t-id || t-statusmarkers || t-bar1_value<br />
|-<br />
| t-bar1_max || t-bar2_value || t-bar2_max || t-bar3_value<br />
|-<br />
| t-bar3_max || t-top || t-left || t-width<br />
|-<br />
| t-height || t-rotation || t-layer || t-aura1_radius<br />
|-<br />
| t-aura1_color || t-aura2_radius || t-aura2_color || t-aura1_square<br />
|-<br />
| t-aura2_square || t-tint_color || t-light_radius || t-light_dimradius<br />
|-<br />
| t-light_angle || t-light_losangle || t-light_multiplier || t-light_otherplayers<br />
|-<br />
| t-light_hassight || t-flipv || t-fliph || t-controlledby<br />
|-<br />
| t-_cardid || t-_pageid || t-imgsrc || t-bar1_link<br />
|-<br />
| t-bar2_link || t-bar3_link || t-represents || t-layer<br />
|-<br />
| t-isdrawing || t-name || t-gmnotes || t-showname<br />
|-<br />
| t-showplayers_name || t-showplayers_bar1 || t-showplayers_bar2 || t-showplayers_bar3<br />
|-<br />
| t-showplayers_aura1 || t-showplayers_aura2 || t-playersedit_name || t-playersedit_bar1<br />
|-<br />
| t-playersedit_bar2 || t-playersedit_bar3 || t-playersedit_aura1 || t-playersedit_aura2<br />
|-<br />
| t-lastmove || t-adv_fow_view_distance || t-has_bright_light_vision || t-has_night_vision<br />
|-<br />
| t-night_vision_distance || t-emits_bright_light || t-bright_light_distance || t-emits_low_light<br />
|-<br />
| t-low_light_distance || t-has_limit_field_of_vision || t-limit_field_of_vision_center || t-limit_field_of_vision_total<br />
|-<br />
| t-has_limit_field_of_night_vision || t-limit_field_of_night_vision_center || t-limit_field_of_night_vision_total || t-has_directional_bright_light<br />
|-<br />
| t-directional_bright_light_center || t-directional_bright_light_total || t-has_directional_dim_light || t-directional_dim_light_center<br />
|-<br />
| t-directional_dim_light_total || t-lightColor || || |<br />
|}<br />
<br />
'''''It is important to note that some attributes names on tokens have corresponding attribute names on characters, which represent different values. For example, [*T:id] returns the character ID, while [*T:t-id] returns the token ID.'''''<br />
<br />
=== Subroutine Parameters ===<br />
<br />
When using a gosub statement (-->) or a conditional marked as a gosub (prefixing the label with a > character), you can pass any number of parameters separated by semicolons (;) that the code in the subroutine can utilize.<br />
<br />
Subroutine parameters are numbered starting at 1, and are accessed by using the notation [%number%], so the first parameter is [%1%], the second is [%2%], etc.<br />
<br />
Parameter substitution happens on all line types, and happens prior to character attribute references or roll variable substitution.<br />
<br />
=== Campaign Attribute ===<br />
You can retrieve properties of the API's Campaign object with the [*C:attributename] syntax. For example, [*C:playerpageid] will retrieve the current player ribbon page from the Campaign object.<br />
<br />
=== Page Attributes ===<br />
If you have set the '''activepage''' parameter, you can retrieve page-related properties with the [*P:attributename] syntax, including the page's UDL parameters.<br />
<br />
=== Repeating Section Values ===<br />
<br />
You can reference repeating attribute data using the syntax [*R:attributename] syntax (similar to referencing standard character attributes). The currently active repeating row information will be used to retrieve attribute values. You can also retrieve the full attribute name for a repeating row attribute by using the [*R>attributename] notation. This is useful to pass to things like chatsetattr.<br />
<br />
=== Array Elements ===<br />
After an array has been declared, the elements can be referenced with [@arrayName(index)]. Array indices start at 0.<br />
<br />
== Deferred Resolution for Meta Scripts ==<br />
<br />
As of 1.2.9, ScriptCards supports a deferral character for use when calling another API script with via the --@ statement, to defer processing of meta script references so they get processed prior to the sub-API call insted of prior to ScriptCards execution. To defer this processing for meta script (SelectManager, Fetch) by inserting a deferral character into the meta call. For example, if I want to have ScriptCards call TokenMod as if the token for "Quej Gr'stra" (yes, I let Roll20 name my test NPCs) I could use something like this:<br />
<br />
--@token-mod|{^& select Quej Gr'stra} _on showname<br />
<br />
The "^" in between { and & will prevent SelectManager from seeing the call when the ScriptCard script is processed, but the --@ statement will remove the deferral character so the command that will be sent by ScriptCards is:<br />
<br />
!token-mod {& select Quej Gr'stra} --on showname<br />
<br />
With the deferral character removed, SelectManager will see the {& select ...} and do its magic.<br />
<br />
While the default deferral character is "^", the deferral character is a setting that can be changed:<br />
<br />
--#deferralcharacter|%<br />
<br />
Will make % the deferral character for future --@ statements in the running script.<br />
<br />
There are currently three supported Meta script structures: {^&...} for SelectManager, @^(...) and *^(...) for fetch, where the ^ in the structures here represents the placement of the deferral character.<br />
<br />
== Arrays ==<br />
<br />
Arrays are a new data type introduced in version 1.1.12 of ScriptCards, and are manipulated with associated function (--~) commands.<br />
<br />
* Arrays are a lists of strings. Items in an array cannot contain the semi-colon (;) character, as that is used to separate parameters in the function code that deals with arrays.<br />
* Arrays are accessed via the --~ script command. In some cases, the value of the tag (variable name) for array commands is not used, and can be a dummy value or simply omitted. I have omitted them in the statements below.<br />
* All commands that DO return a value return string values, even if the content is numeric.<br />
* If a command returns a value and there is some sort of reason that it isn't an array value, you will get "ArrayError" in the return value. This can happen if you reach the end of an array while stepping through it, for example, so checking for "ArrayError" can serve as the end condition for a loop.<br />
* Each array keeps track of its current index, allowing you to step forward and backwards through arrays.<br />
* Any number of arrays can be defined.<br />
* Unlike string variables and roll variables, array variables cannot (currently) be referenced directly. It is necessary to use the function (--~) syntax to manipulate arrays and get values from them as strings for use in other parts of your script.<br />
<br />
<br />
== Reentrant Scripts ==<br />
<br />
Reentrant scripts allow you to create buttons in your script code that will re-execute the script at a given label within the code. If you set the reentrant setting (--#reentrant|somevalue) to a non-zero value, your setting and variable information will be preserved between executions. Reentrant script can be used to present menus or choices and then continue acting.<br />
<br />
Reentrant buttons are created with the [rbutton]Caption::ReentryLabel;Parameter[/rbutton] construct. The caption will be displayed on the generated button. ReentryLabel is the name of a label in your script that the button will jump to when clicked, and Parameter will be passed in as a string value called "reentryval".<br />
<br />
Example:<br />
<pre><br />
!script {{<br />
--#reentrant|testing<br />
--=Roll|1d20<br />
--+Roll|[$Roll]<br />
--&String|That was a [$Roll.Raw]!<br />
--~x|array;define;MyArray;Apple;Banana;Orange<br />
--+Try it|[rbutton]Hello!::EXEC_PC_SPELL;9[/rbutton]<br />
--X|<br />
<br />
--:EXEC_PC_SPELL|<br />
--+ReentryVal|[&reentryval]<br />
--+The value of Roll is|[$Roll]<br />
--+Value of String|[&String]<br />
--+Array|[@MyArray(0)]<br />
--X|<br />
}}<br />
</pre><br />
<br />
This script sets up some variables and then displays a button labeled "Hello!". If the user clicks the button, the script will be re-entered starting at the "EXEC_PC_SPELL", which will display the content of the variables from the original execution.<br />
<br />
'''''Note: This section needs to be expanded upon'''''<br />
<br />
== Procedure Libraries ==<br />
<br />
You can now create handouts in your game in Roll 20 with the name format "ScriptCards Library NAME", where name is a name you assign to the library. Library names are case sensitive. It is my hope that the more proficient ScriptCards scripters out there will provide procedure libraries (or procedures that can be included in libraries) for others to use to make their scripting life easier. Be they specific to a game system, or to a type of activity, I think a robust set of libraries that GMs could use to enhance their scripting capabilities would be very valuable to the community. Should such things begin to emerge, I’ll create a portion of the ScriptCards Wiki page to house them.<br />
<br />
To include one or more libraries in a script, use the +++libname+++ directive (does not need a -- line associated with it). Multiple library names can be specified by separating them with semicolons (i.e., +++General;dnd5elib;Colorize+++ would include three libraries (General, dnd5elib, and Colorize).<br />
<br />
Included libraries are separated from the main script code by the automatic inclusion of "--X|" before the first library is appended to the script, and all libraries are loaded at the end of the script before script processing takes place.<br />
<br />
Procedures and labels in libraries can be used just as if they were included in the body of your script. Note that this DOES mean that you could, technically, jump into a library with a direct branch (--^) or direct branch conditional, but I recommend using libraries to store reusable procedures.<br />
The Notes section of the library handout stores the library code, and is written just like any other ScriptCards code except:<br />
<br />
* They cannot use roll queries (?{Some Prompt:}) to get information from the user at execution time.<br />
* They cannot use @{} notation to access character and token information.<br />
<br />
Both of these limitation stem from the fact that Procedure Libraries are not processed by the chat server, which is what handles these items.<br />
<br />
Here is an example of handling damage modifications (resistance, vulnerability, and immunity) in D&D 5E with a library:<br />
<br />
<pre><br />
!script {{<br />
+++dnd5elib+++<br />
--#|Damage Modifiers Test<br />
--#targettoken|@{target|token_id}<br />
-->Lib5E_CheckDamageModifiers|ResistType;fire<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] fire damage<br />
<br />
-->Lib5E_CheckDamageModifiers|ResistType;cold<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] cold damage<br />
<br />
-->Lib5E_CheckDamageModifiers|ResistType;poison<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] poison damage<br />
<br />
-->Lib5E_CheckDamageModifiers|ResistType;acid<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] acid damage<br />
<br />
--X|<br />
}}<br />
</pre><br />
<br />
Library content (In a handout called “ScriptCards Library dnd5elib” NOTE: Paste into Notepad first and then paste into the handout in Roll20 to avoid bringing over HTML formatting from the web site):<br />
<br />
<pre><br />
--/|ScriptCards Library: dnd5elib version 0.0.1<br />
--/|Provides various utility procedures for D&D 5E games<br />
<br />
--/|Lib5E_CheckDamageModifiers handle damage resistance, vulnerability, and immunity. <br />
--/|Pass a string variable to be filled with a string to be appended to a dice roll and the damage type <br />
<br />
--:Lib5E_CheckDamageModifiers|damageVariableName;damageType<br />
--&[%1%]|<br />
--?"[*T:npc_vulnerabilities]" -inc "[%2%]"|>_Lib5E_IsVulnerable;[%1%]<br />
--?"[*T:npc_resistances]" -inc "[%2%]"|>_Lib5E_IsResistant;[%1%]<br />
--?"[*T:npc_immunities]" -inc "[%2%]"|>_Lib5E_IsImmune;[%1%]<br />
--<|<br />
<br />
--:_Lib5E_IsVulnerable| --&[%1%]| * 2 [Vulnerable] --<|<br />
--:_Lib5E_IsResistant| --&[%1%]| \ 2 [Resistant] --<|<br />
--:_Lib5E_IsImmune| --&[%1%]| * 0 [Immune] --<|<br />
</pre><br />
<br />
The idea is that the functions in the library create a string that can be appended to a roll to modify the output based on resistances, so you pass Lib5E_CheckDamageModifiers the name of the string variable you want to use and the damage type. The variable (ResistType in this case) will include either nothing, “* 2 [Vulnerable]”, “\ 2 [Resistant]”, or “* 0 [Immune]” which can be included in a roll assignment (--=) to modify the damage as appropriate. The order here might be important if an NPC is misconfigured to be both resistant and immune to the same damage type. Since immune is an absolute, having it last ensures that it will override resistant or vulnerable. A creature that is both vulnerable and resistant (again, misconfigured) will come back as resistant since that condition is checked after vulnerable.<br />
Some notes: I prefix my library labels with either “Lib5E_” or “_Lib5E_” as a clarity convention. This isn’t strictly necessary but you should be aware that if two libraries (or if your script and a library) define the same label, the last label defined will win. Since libraries are appended to the end of the script in the order you include them in the +++libname+++ directive, you can somewhat control this, but it is probably best to avoid re-declaring labels. <br />
<br />
In my case, items beginning with “Lib5E_” are intended to be called by scripts, while items beginning with “_Lib5E_” are intended to be used as subroutines by the “public” procedures. Of course, there is no reason you couldn’t call them directly.<br />
<br />
You might also note that I’ve included some library information in comment lines (--/|) at the top of the library. These are ignored by ScriptCards, and are a good way to convey requirements, parameters, usage information, etc.<br />
<br />
== Example Libraries ==<br />
<br />
=== dnd5elib ===<br />
<br />
[https://github.com/kjaegers/ScriptCards Download the dnd5elib Library from the ScriptCards GitHub]<br />
<br />
The '''dnd5elib''' library provides a collection of utility procedures that help simplify dealing with the D&D 5E Official Sheet. Some of the procedures in this library require '''chatsetattr''' to be installed in your game. This is a growing library, and currently only has a handful of routines. They are:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Procedure Name !! Notes<br />
|-<br />
| style="white-space:nowrap" | Lib5E_CheckDamageModifiers || This procedure can be used to evaluate vulnerabilities, resistances, and invulnerabilities on an NPC. After setting the --#target| parameters, pass the Lib5E_CheckDamageModifiers procedure a variable name (no reference information) and a damage type (i.e., fire, cold, bludgeoning, etc.) and a string variable with the name passed in as the first parameter will be created that contains text that can be included in a roll line (--=) in order to modify the roll as appropriate. For example, '''-->Lib5E_CheckDamageModifiers|ResistType;fire''' will check the current target character's attributes for "fire" and will either return an empty string (no references), "* 0 [Immune]" if the creature is immune, "\ 2 [Resistant]" if the creature is resistant, or "* 2 [Vulnerable]" if the creature is vulnerable to fire damage.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_DeductSpellSlot || Pass in a character_id and a slot level, and the script will expend one spell slot of that level, capping the value at 0 slots remaining. For Example '''<nowiki>-->Lib5E_DeductSpellSlot|@{selected|character_id};1</nowiki>''' to deduct a first level spell slot from the selected character.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_FindResource || Used to locate a resource value on a character. Pass in a character_id, a resource name, and two variable names. The procedure will check both repeating and non-repeating resources looking for a resource whose name matches what was passed in and return three variables. The first will be a string variable named for the 3rd parameter and contains the attribute name of the resource's "name" field. The second will be a string variable named after parameter 4 and contains the resource's value field attribute name, and the third variable is a Roll Variable, also named after the 4th parameter that contains the current resource value. Example: '''<nowiki>-->Lib5E_FindResource|@{selected|character_id};Crossbow bolts;ResName;ResValue</nowiki>''' will find "Crossbow bolts" as a resource on the character and return [&ResName] which is the name of the resource attribute, [&ResValue] which is the '''name of the attribute that stores the value''' and [$ResValue] which is the current numeric value of the resource.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Global_Attack_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Attack Modifiers (repeating_tohitmod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Bless" for 1d4 active and "Being Cool" for +2 active, I will get a return string " + 1d4 [Bless] + 2 [Being Cool]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Save_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Save Modifiers (repeating_savemod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Bless" for 1d4 active and "Being Cool" for +2 active, I will get a return string " + 1d4 [Bless] + 2 [Being Cool]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Skill_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Skill Modifiers (repeating_skillmod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Guidance" for 1d4 active and "Being Cool" for +2 active, I will get a return string " + 1d4 [Guidance] + 2 [Being Cool]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_AC_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Save Modifiers (repeating_savemod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Shield of Faith" with a value of 2 active, I will get a return string " + 2 [Shield of Faith]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Damage_Modifiers || Pass a character ID and TWO string variable to set the return value. The first string will be for normal damage, and the second will be the additional damage on a crit. This procedure will look through the Global Damage Modifiers (repeating_damagemod_*) for rows that are active (checked on the character sheet) and return two strings with the dice rolls and descriptions for them (for example, if I have "Sneak Attack" with a value of 1d6 normal and 1d6 critical damage active, I will get a return string " + 1d6 [Sneak Attack]" and another string of " + 1d6 [Sneak Attack CRIT]" that can be used in a dice rolls.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_DivineSmiteDice || Used to calculate the number of dice to be rolled for a paladin's Divine Smite. Pass a target token id, a spell slot level, and a string variable to be set to the dice roll amount based on the NPC_TYPE attribute of the target token. The returned variable will contain a dice roll (like "3d8" that can be used in a --= line)<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Character_Summary || Pass a character ID to outputs a mini character sheet, including clickable buttons for attacks, actions, legendary actions, etc. Will automatically detect a PC vs NPC and output the appropriate sections.<br />
|}<br />
<br />
Due to formatting issues with the Wiki, the library code has been moved to a [https://gist.github.com/kjaegers/52f6049ddd257f0a1288aca4bbde13c5 GITHUB GIT]. Please view the GIST in raw mode and copy the text and paste it into a handout called "ScriptCards Library dnd5elib" in your Roll20 Game.<br />
<br />
== What to Know if you are Coming from PowerCards ==<br />
<br />
''Note: This section is a work in progress.''<br />
<br />
While ScriptCards and PowerCard have very similar output goals, their internals and use are quite different. The table below summarizes some of the major differences between the scripts.<br />
<br />
::{| class="wikitable"<br />
|-<br />
! PowerCards !! ScriptCards <br />
|-<br />
| With a handful of exceptions, all lines in a PowerCard macro are intended to produce a line of output on the final card. || With ScriptCards, ONLY the <code>--+</code> and <code>--*</code> statement types produces output <br />
|-<br />
| PowerCards lines begin with two dashes (<code>--</code>) followed by a unique tag name for the line, followed by a vertical bar and the content for the line. || ScriptCards lines begin with two dashes (<code>--</code>) followed by a '''statement type identifier''', which is a single character that identifies the type of line to the interpreter. This is followed by a tag (frequently optional), a vertical bar, and the parameters for the statement being executed.<br />
|-<br />
| PowerCard macros are always processed top to bottom. Lines can be hidden so they don't output anything, but there is no looping or branching (--SkipTo looks like a branch, but it just hides all of the lines until the referenced label. || ScriptCards scripts support true branching, including direct branching (<code>--^</code>) and procedure branching (<code>--></code>) and (<code>--<</code>). Procedures support parameters and a call stack so procedures can be nested to call other procedures.<br />
|-<br />
| All lines in a PowerCards macro need to have unique tags because PowerCards builds the card as a single JavaScript object using the tag names to store what will be displayed. This is why repeated tag names always result in the last one being shown. || ScriptCards tags do not need to be unique, and in the case of many line types are optional.<br />
|-<br />
| PowerCards conditionals result in either showing or hiding the line they are on. || ScriptCards conditionals '''''only''''' support branching as the result of the comparison. This branching can be direct (a GOTO) or procedural (a GOSUB) '''''NOTE: As of version 1.2.0, ScriptCards also supports roll/string variable assignment as a result of conditional evaluation'''''<br />
|-<br />
| PowerCards relies on the Roll20 [[Quantum Roll]] server and inline rolls for all dice functions || ScriptCards includes its own dice roll parser, and '''''does not support''''' inline rolls.<br />
|-<br />
| PowerCards RollIDs (often mistaken for variables) are assigned by analyzing the results of an inline roll, and cannot be referenced in other rolls, so you can't roll a <code>1d4</code> and then roll a <code>1d20</code> and add the <code>1d4</code> result because all of the rolls happen on the chat server before PowerCards gets the macro text. || ScriptCards supports two types of variables: Roll Variables and String Variables. Because ScriptCards uses its own roll parser and is not dependent upon the chat server, rolls and their results can be used in other rolls, math functions, output, etc.<br />
|}<br />
<br />
== Example Scripts ==<br />
<br />
Below are some sample scripts that utilize the various statement types in ScriptCards:<br />
<br />
=== Divine Smite ===<br />
<br />
This script will prompt the user for a spell slot level to expend on a divine smite. It will check the target's npc_type to see if it is an Undead or Fiend, which adds an additional d8 to the smite roll.<br />
<br />
[[File:ScriptCards Divine Smite.png|Divine Smite Script Output]]<br />
<br />
<pre><br />
!scriptcard {{<br />
--#title|Divine Smite<br />
--=DiceCount|?{Spell Slot Level?|1|2|3|4|5|6|7|8|9} + 1<br />
--=IsFiendOrUndead|0<br />
--?"@{target|npc_type}" -inc fiend|>IsBoosted<br />
--?"@{target|npc_type}" -inc undead|>IsBoosted<br />
--=TotalDice|[$DiceCount] + [$IsFiendOrUndead]<br />
--=SmiteRoll|[$TotalDice]d8<br />
--#emoteText|@{selected|token_name} smites @{target|token_name}<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
--+Smite|deals [$SmiteRoll] radiant damage.<br />
--X|<br />
<br />
--:IsBoosted|<br />
--=IsFiendOrUndead|1<br />
--<|<br />
}}<br />
</pre><br />
<br />
==== How It Works ====<br />
<br />
The first line sets the "title" card parameter to "Divine Smite".<br />
<br />
Line 2 Shows a query to the user asking for the spell slot level, adds one and stores the value in the "DiceCount" Roll Variable. The query/dropdown is generated by the chat server prior to the script being executed.<br />
<br />
Line 3 defaults the "IsFiendOrUndead" Roll Variable to 0.<br />
<br />
Lines 4 and 5 compare the target's "npc_type" attribute (passed by the chat server as text) to see if they include either "undead" or "fiend". If true, the IsBoosted subroutine will be called. No parameters are passed to this subroutine.<br />
<br />
Line 6 sets the "TotalDice" variable to the base (DiceCount) number plus the IsFiendOrUndead number, which will be a 0 or a 1.<br />
<br />
Line 7 calculates "SmiteRoll" by rolling a number of d8 equal to the "TotalDice" value.<br />
<br />
Lines 8-10 set the parameters for the emote, which appears above the card content. By setting the sourceToken and the targetToken, their icons will appear in the emote surrounding the text describing the action.<br />
<br />
Line 11 is the only line that actually produces output on the card. It results in "Smite deals # radiant damage".<br />
<br />
Line 12 ends the script execution, preventing the script from continuing and running the subroutines out of context.<br />
<br />
Lines 14-16 are the IsBoosted subroutine, starting with the :IsBoosted label. The IsFiendOrUndead variable is set to 1, and a return from subroutine is executed.<br />
<br />
=== Magic Missile ===<br />
<br />
This script demonstrates using a loop and calling a subroutine to fire a number of missiles determine by the spell slot level used to cast the spell.<br />
<br />
[[File:ScriptCards_MagicMissile_Fixed.png|Magic Missile Script Output]]<br />
<br />
<pre><br />
!scriptcard {{ <br />
--#title|Magic Missile<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
--=MissileCount|?{Spell Slot Level?|1|2|3|4|5|6|7|8|9} + 2<br />
--=DisplayCount|1<br />
--=MissileDamage|0<br />
--#leftsub|Slot level ?{Spell Slot Level?}<br />
--#rightsub|Ranged Attack<br />
--#emoteText|Fred uses a level ?{Spell Slot Level?} spell slot to fire [$MissileCount.Total] missiles of magical force!<br />
--:MissileLoop|<br />
-->FireMissile|<br />
--=DisplayCount|[$DisplayCount] + 1<br />
--?[$DisplayCount] -le [$MissileCount]|MissileLoop<br />
--+Total|Total damage is [$MissileDamage]<br />
--X|<br />
<br />
--:FireMissile|<br />
--=ThisMissile|1d4 + 1<br />
--=MissileDamage|[$MissileDamage] + [$ThisMissile]<br />
--+Missile|[$DisplayCount.Total] Hits for [$ThisMissile] [b]force[/b] damage<br />
--<|<br />
}}<br />
</pre><br />
<br />
==== How It Works ====<br />
<br />
Lines 1-3 set the card title, the source token and the target token. Setting these tokens causes their icons/avatars to appear in the Emote section of the card.<br />
<br />
Line 4 asks the user what spell slot level they wish to use to cast magic missile. The number of missiles fired is equal to 2 plus the spell level, and this is stored in the MissileCount variable.<br />
<br />
Line 5 stores a 1 in the DisplayCount variable. This will be used to control the loop to determine the number of missiles fired and the missile number when displaying damage rolls.<br />
<br />
Line 6 initializes MissileDamage to 0<br />
<br />
Line 7 sets the left subtitle to the text "Slot Level #", where # is the spell slot level being used.<br />
<br />
Line 8 sets the right subtitle to the text "Ranged Attack".<br />
<br />
Line 9 sets the emoteText parameter with a description of the action, including the slot level and number of missiles fired.<br />
<br />
Line 10 is a label for the missile firing loop<br />
<br />
Line 11 Calls the "FireMissile" subroutine<br />
<br />
Line 12 increases the DisplayCount variable by 1<br />
<br />
Line 13 Checks to see if there are still missles to fire (DisplayCount <= MissileCount) and if so branches to MissileLoop<br />
<br />
Line 14 Displays the total damage dealt by the spell.<br />
<br />
Line 15 stops execution of the script to prevent out of context execution of the subroutine.<br />
<br />
Lines 76-21 are the FireMissile subroutine, beginning with the FireMissile label. The 1d4+1 is rolled and assigned to "ThisMissile". The result is added to the existing MissileDamage total, and a line for the current missile is displayed with the missile number and the damage for the missile.<br />
<br />
=== Longsword Attack ===<br />
<br />
This script demonstrates a standard 5E D&D melee weapon attack, including detection of misses, fumbles, hits, and critical hits. If installed, alterbars is used to decrement the target's BAR3 value by the damage dealt.<br />
<br />
[[File:ScriptCards Longsword.png|Longsword Script Output]]<br />
<br />
<pre><br />
!scriptcard {{<br />
--#title|Longsword<br />
--#leftsub|Melee Attack<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
--#emoteText|@{selected|token_name} attacks @{target|token_name}<br />
--=TargetAC|@{target|npc_ac}<br />
--?[$TargetAC.Total] -gt 0|DoneWithAC<br />
--=TargetAC|@{target|ac}<br />
--:DoneWithAC|<br />
--=AttackRoll|1d20 + @{selected|strength_mod} [STR] + @{selected|pb} [PROF]<br />
--+Attack|@{selected|token_name} rolls [$AttackRoll] vs AC [$TargetAC].<br />
--?[$AttackRoll.Base] -eq 20|Crit<br />
--?[$AttackRoll.Base] -eq 1|Fumble<br />
--?[$AttackRoll.Total] -ge [$TargetAC.Total]|Hit<br />
--+Miss|The attack missed.<br />
--^Final|<br />
<br />
--:Fumble|<br />
--+Fumble!|The attack went horribly wrong.<br />
--^Final|<br />
<br />
--:Hit|<br />
--=Damage|1d8 + @{selected|strength_mod} [STR]<br />
--+Hit!|The attack hit @{target|token_name} for [$Damage] slashing damage.<br />
--@alter|_target|@{target|token_id} _bar|3 _amount|-[$Damage]<br />
--^Final|<br />
<br />
--:Crit|<br />
--=Damage|1d8 + @{selected|strength_mod} [STR] + 1d8 [CRIT]<br />
--+Critical Hit!|The attack hit @{target|token_name} for [$Damage] slashing damage.<br />
--@alter|_target|@{target|token_id} _bar|3 _amount|-[$Damage]<br />
<br />
--:Final|<br />
}}<br />
</pre><br />
<br />
==== How it Works ====<br />
<br />
In lines 1-5, we set the title, subtitle, and emote text along with the tokens for the emote area.<br />
<br />
Lines 6-9 allow us to determine the AC of the target. On the 5E Roll20 sheet, NPCs armor class is stored in "npc_ac", while PCs armor class is in "ac". First we grab npc_ac and if it is zero, we check AC.<br />
<br />
Line 10 rolls the attack roll, rolling 1d20 and adding the attacker's strength modifier and proficiency bonus<br />
<br />
Line 11 displays the result of the attack roll on the card<br />
<br />
Lines 12-14 determine what kind of result the attack had. If the .Base value of the roll was 20, we branch to "Crit". If it was 1, we branch to "Fumble". If the .Total value of the roll was greater than or equal to the AC that was determined in Lines 6-9, we branch to Hit.<br />
<br />
Assuming we didn't branc anywhere, the result of the attack was a miss, so we display that on line 15 and then branch to "Final"<br />
<br />
This is followed by three branch segments, :Fumble, :Hit, and :Crit. A fumble displays a text message and branches to :Final.<br />
<br />
On a hit or a crit, we roll Damage (adding additional damage dice on a crit). We display a "Hit!" or "Critical Hit!" message and then make an API call to AlterBars, passing it the token id, bar we want to modify (3 in this case), and the amount we want to modify by the Damage value.<br />
<br />
=== Party Health Status ===<br />
<br />
This example calculates the current Hit Points remaining and HP percentage for each character and creates a color-coded display with the current party status.<br />
<br />
[[File:ScriptCards Party Health.png]]<br />
<br />
<pre><br />
!scriptcard {{<br />
--#title|Party Status<br />
--#titleCardBackground|#33CC33<br />
--#oddrowbackground|#bfee90<br />
--#evenrowbackground|#90eebf<br />
-->HealthCheck|@{Quej Grastra|character_id}<br />
-->HealthCheck|@{Brim Cheuto|character_id}<br />
-->HealthCheck|@{Odug Ututees|character_id}<br />
--X|End of card Execution<br />
<br />
--:HealthCheck|<br />
--=HealthPerc|[*[%1%]:hp] / [*[%1%]:hp^] * 100 \ 1<br />
--=HealthColor|000000<br />
--?[$HealthPerc.Total] -gt 50|HealthSkip<br />
--=HealthColor|FF0000<br />
--:HealthSkip|<br />
--+[*[%1%]:character_name]|has [#[$HealthColor.RollText]][*[%1%]:hp] of [*[%1%]:hp^][/#] HP [R]([$HealthPerc.Total]%)[/R]<br />
--<|End of HealthCheck<br />
}}<br />
</pre><br />
<br />
==== How it Works ====<br />
<br />
Lines 1-4, we set the card title, and set the title background and row background colors to shades of green.<br />
<br />
Lines 5-7 make gosub calls the the "HealthCheck" subroutine, passing in the character ID of each of the named characters (these are the names of the characters in my test game)<br />
<br />
Line 8 terminates the script execution.<br />
<br />
The remaining lines of the script are the HealthCheck subroutine, which works like this:<br />
<br />
Line 10 is the subroutine label (:HealthCheck)<br />
<br />
Line 11 uses the character id passed as a parameter and combines it with character attribute lookup *(...) to retrieve the value of "hp" and "hp<nowiki>^</nowiki>" for the character. The <nowiki>^</nowiki> character is used to specify that we want the MAX value for this attribute for the second call. We divide these two numbers and multiple by 100 to get a percentage. Finally, we use integer division by 1 to round the percentage and drop the decimals. The end result gets stored in the HealthPerc roll variable.<br />
<br />
Line 12 defaults to color of the health text to black<br />
<br />
Line 13 check to see if the health percentage is greater than 50. If so, it branches to HealthSkip, preventing the script from executing line 13.<br />
<br />
Line 14 sets the color of the health text to red<br />
<br />
Line 15 is the label that will be branched to from Line 13 to skip the red coloring<br />
<br />
Line 16 again uses character attribute substitution and the passed parameter value to output a display line containing the character name, the colorized health total, and the percentage value. The percentage is right-justified.<br />
<br />
Line 17 returns from the HealthCheck subroutine.<br />
<br />
=== Expanded Magic Missile Script ===<br />
<br />
This is the expanded and enhanced version of the Magic Missile script covered in {{yt|watch?v=u50xvNzS9Zk | this video}}. It includes visual and audio effects, checking and deducting spell slots, and applying damage using either Token-Mod or Alterbars.<br />
<br />
<pre><br />
!scriptcard {{ <br />
--#title|Magic Missile<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
<br />
-->GetAndCheckSlotInformation|<br />
<br />
--=MissileCount|[$SlotLevel] + 2<br />
--=DisplayCount|1<br />
--=MissileDamage|0<br />
--#leftsub|Slot level [$SlotLevel]<br />
--#rightsub|Ranged Attack<br />
--#emoteText|@{selected|character_name} uses a level [$SlotLevel.Total] spell slot to fire [$MissileCount.Total] missiles of magical force!<br />
<br />
--:MissileLoop|<br />
-->FireMissile|<br />
--=DisplayCount|[$DisplayCount] + 1<br />
--?[$DisplayCount] -le [$MissileCount]|MissileLoop<br />
--+Total|Total damage is [$MissileDamage]<br />
-->DeductSpellSlot|<br />
--#rightsub|Level [$SlotLevel] Left: [$SlotsRemaining] <br />
-->PlayEffects|none;burst-smoke;beam-magic;spell_01<br />
-->ApplyDamageTokenmod|@{target|token_id};3;-[$MissileDamage]<br />
-->ApplyDamageAlterbars|@{target|token_id};3;-[$MissileDamage]<br />
--X|<br />
<br />
--:FireMissile|<br />
--=ThisMissile|1d4 + 1<br />
--=MissileDamage|[$MissileDamage] + [$ThisMissile]<br />
--+Missile|[$DisplayCount.Total] Hits for [$ThisMissile] [b]force[/b] damage<br />
--<|<br />
<br />
--:GetAndCheckSlotInformation|<br />
--=SlotLevel|?{Spell Slot Level?|1|2|3|4|5|6|7|8|9}<br />
--=SlotsTotal|[*S:lvl[$SlotLevel]_slots_total]<br />
--=SlotsExpended|[*S:lvl[$SlotLevel]_slots_expended]<br />
--?[$SlotsExpended.Total] -ge [$SlotsTotal.Total]|NoSlotsLeft<br />
--<|<br />
<br />
--:NoSlotsLeft|<br />
--+|[*S:character_name] has no level [$SlotLevel.Total] spell slots available.<br />
--X|<br />
<br />
--:DeductSpellSlot|<br />
--=SlotsExpended|[$SlotsExpended] + 1<br />
--@setattr|_charid [*S:character_id] _lvl[$SlotLevel]_slots_expended|[$SlotsExpended] _silent<br />
--=SlotsRemaining|[$SlotsTotal] - [$SlotsExpended]<br />
--<|<br />
<br />
--:PlayEffects|Parameters are : source effect; target effect; line effect; sound effect<br />
--vtoken|@{selected|token_id} [%1%]<br />
--vtoken|@{target|token_id} [%2%]<br />
--vbetweentokens|@{selected|token_id} @{target|token_id} [%3%]<br />
--@roll20AM|_audio,play,nomenu|[%4%]<br />
--<|<br />
<br />
--:ApplyDamageTokenmod|Parameters are tokenid;bar#;amount<br />
--@token-mod|_ignore-selected _ids [%1%] _set bar[%2%]_value|[%3%]<br />
--<|<br />
<br />
--:ApplyDamageAlterbars|<br />
--@alter|_target|[%1%] _bar|[%2%] _amount|[%3%]<br />
--<|<br />
}}<br />
</pre><br />
<br />
[[Category:Featured articles]]</div>5004103https://wiki.roll20.net/Script:ScriptCardsScript:ScriptCards2021-10-01T10:25:58Z<p>5004103: /* Repeating Section Access (--R) */</p>
<hr />
<div>{{revdate}}<br />
== Introduction ==<br />
'''ScriptCards''' provides a script interpreter that can be used to create powerful macros that display the results of player/NPC actions, or display other information in a pleasing visual format in your game's chat window. The scripting language contains variables (both dice-roll (enhanced numerics) and strings) as well, conditionals, branching, subroutines with parameters, and a set of built-in functions to simplify working with Roll20 information.<br />
{{script overview<br />
|name=ScriptCards<br />
|author={{user profile|2365448|Kurt J.}}<br />
|code=<br />
|version=1.4.0e<br />
|lastmodified=2021-09-24}}<br />
ScriptCards is not game-system specific, and can be used with any system/sheet. Near the end of this Wiki there is a section set aside for libraries that can implement system-specific tasks, with the hope that enthusiasts playing particular systems will create and share utility functions that can be utilized by the wider community.<br />
<br />
The default display style for ScriptCards output is similar to the format used to document player and NPC abilities in Dungeons and Dragons 4th Edition, but does not have any system ties to D&D4E.<br />
<br />
Current OneClick Version : 1.4.0e<br />
<br />
Current Development Version : 1.4.4<br />
<br />
'''''<big>Critically Important: ScriptCards does not use/parse inline rolls. ScriptCards includes its own built-in dice roll parser to allow for the use of variables inside dice rolls. As of version 1.2.3, ScriptCards will now take inline rolls and substitute the total result value in statement strings, meaning that you can utilize inline rolls but ScriptCards will only see the result of the roll, and not parse the roll components itself.</big>'''''<br />
<br />
* {{fpl|9752053/ ScriptCards thread}}<br />
** {{fpl|10000297/ Scritpcard API Working and Sharing}}<br />
* https://github.com/kjaegers/ScriptCards/tree/main/ScriptCards_API - GitHub repository for source before the one-click version is updated.<br />
* {{yt.be|hyR7Jnq4mQM ScriptCards Intro}} 45min, Jan 2021<br />
* {{yt.be|u50xvNzS9Zk ScriptCards Magic Missile Deep Dive}} 39min, Feb 2021<br />
<br />
<br />
__TOC__<br />
=== Is ScriptCards Related to [[PowerCards]]? ===<br />
<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
Check the '''[[#What to Know if you are Coming from PowerCards|What to Know if you are Coming from PowerCards]]'''-section for a comparison table between the two scripts.<br />
<br />
== What is a ScriptCard Script ==<br />
<br />
A ScriptCard Script is text written into the chat window (either typed directly, pasted, or run via a macro) that will produce a card of information in the [[text Chat|chat window]]. A ScriptCard Script is composed of an [[API]] command: <code><nowiki>!scriptcard {{ }}</nowiki></code> enclosing any number of lines that determine the output that will be added to the card. At it simplest, the following macro:<br />
<br />
<pre>!scriptcard {{ }}</pre><br />
<br />
Will produce just a title card that displays “ScriptCards” as the name:<br />
<br />
[[File:Scriptcard blank.png]]<br />
<br />
Of course, this is just the simplest type of macro and isn’t very useful. In order to produce useful output, we need to include lines between the <code><nowiki>{{</nowiki></code> and <code><nowiki>}}</nowiki></code> that direct the API script as to what it should do.<br />
<br />
== Structure of a ScriptCard Line ==<br />
<br />
All ScriptCard lines begin with two dashes, followed by an ''statement identifier character'' that lets ScriptCards what type of line it is. There are several of these, and they are detailed in the next section. After the line type identifier, a Tag name 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.<br />
<br />
Following the Tag is a vertical bar, and then the content of the line itself. Again, each type of line might interpret this content differently.<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Identifier !! Statement Type !! Tag !! Content !! Notes<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--/</nowiki> || Comment || unused || unused || The <code>--/</code> 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--#</nowiki> || 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").<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--+</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--=</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--&</nowiki> || Assign String 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. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--@</nowiki> || 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 (i.e., [[TokenMod|!token-mod]], or [[ChatSetAttr|!setattr]], etc.)<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--:</nowiki> || 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<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--^</nowiki> || Branch To || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--></nowiki> || Call Procedure || 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<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--<</nowiki> || 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.<br />
|- <br />
| style="white-space:nowrap" | <nowiki>--?</nowiki> || Conditional Branch || Condition to be evaluated || True Branch Label<nowiki>|</nowiki>False Branch Label || The condition will be evaluated and execution will jump to one of the two indicated branches (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 included a semicolon separated list of parameters. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--s</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--l</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--v</nowiki> || 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+'''''<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--e</nowiki> || Echo to Chat || Name to send chat command as || Chat message to send || Variable substitution takes place on the tag and content.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--R</nowiki> || Retrieve Repeating Section Row information || "find", "first", or "next" || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--~</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--c</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--i</nowiki> || Information Request || User Prompt;Button Caption || InfoType;VariableName;ParameterText || See full documentation below.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--d</nowiki> || 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. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--%</nowiki> || 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. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--*</nowiki> || 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.<br />
|}<br />
<br />
== ScriptCard Statement Type Details ==<br />
The sections below detail the individual statement types supported by ScriptCards<br />
<br />
=== Comment (--/) ===<br />
<br />
A --/ statement is ignored by the ScriptCards parser. You can use this type of statement to add comments and informational text to your script. <br />
<br />
Example:<br />
<pre><br />
!script {{<br />
--/|Script Name : Fireball<br />
--/|Purpose : Allow the player to cast a fireball and blow stuff up!<br />
.<br />
.<br />
.<br />
}}<br />
</pre><br />
<br />
=== Set Parameter (--#) ===<br />
<br />
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.<br />
<br />
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.<br />
<br />
'''''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.'''''<br />
<br />
Examples:<br />
<pre><br />
--#title|Magic Missile<br />
--#leftsub|Level 1 Spell<br />
--#rightsub|Force Damage<br />
</pre><br />
<br />
The three examples above set the “title”, “leftsub”, and “rightsub” values for the card to the content value for the line. <br />
<br />
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.<br />
Settings Lines do not produce output lines on the card.<br />
<br />
The following settings are available (note that parameter names are ''not'' case sensitive):<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Name !! Effect/Use !! Default Value !! Type<br />
|-<br />
| 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<br />
|-<br />
| allowplaintextinrolls || If set to a non-zero value, plain character text in rolls will be copied to the roll text || 0 || Per-Line<br />
|-<br />
| bodyFontFace || Name of the font used in the card rows || Helvetica || Global<br />
|-<br />
| bodyFontSize || Size of the text in the card rows || 14px || Global<br />
|-<br />
| bodybackgroundimage || Specify an image (content for a CSS background-image tag) for the body area || none || Global<br />
|-<br />
| buttonBackground || Background color for buttons created with [button][/button] || #1C6EA4 || Per-Line<br />
|-<br />
| buttonBorderColor || Border (outline) color for buttons created with [button][/button] || #999999 || Per-Line<br />
|-<br />
| buttonFontFace || Font Family specifier for captions on buttons created with [button][/button] || Tahoma || Per-Line<br />
|-<br />
| buttonFontSize|| Text size for captions on buttons created with [button][/button] || x-small || Per-Line<br />
|-<br />
| buttonTextColor|| Text color of labels on buttons created with [button][/button] || #FFFFFF || Per-Line<br />
|-<br />
| 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<br />
|-<br />
| deferralcharacter || Changes the meta script deferral sequence to the specified value || ^ || Per-Line<br />
|-<br />
| diceFontColor|| Color of the dice created with the [d4] [d6], etc. formatting markers || #1C6EA4 || Per-Line<br />
|-<br />
| dicefontsize || Size of the dice created with the [d4] [d6], etc. formatting markers || 3.0em || Per-Line<br />
|-<br />
| 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<br />
|-<br />
| disablerollprocessing || If set to a non-zero value, --= lines will not process dice rolls strings || 0 || Per-Line<br />
|-<br />
| emoteBackground || Background color of the emote area || #f5f5ba || Global<br />
|-<br />
| emoteFont || Name of the font used in emote area (above the title of the output card) || Georgia || Global<br />
|-<br />
| emoteFontColor || Color of the font in the emote area || None (Empty) || Global<br />
|-<br />
| emoteFontSize || Size of the font used in the emote area || 14px || Global<br />
|-<br />
| emoteFontWeight || Font weight for the font in the emote area || bold|| Global<br />
|-<br />
| emoteState || If set to anything other than "visible", the emote portion of the card will not be displayed || visible || Global<br />
|-<br />
| emoteText || Text to display in the emote portion of the card || None (Empty) || Global<br />
|-<br />
| emotefont || Name of the font used in the emote text area || font-family: Georgia, serif; font-weight: bold; || Global<br />
|-<br />
| evenRowBackground || Hex code for the background color for even rows || #eeeeee || Per-Line<br />
|-<br />
| evenRowFontColor || Hex code for the text color for even rows || #000000 || Per-Line<br />
|-<br />
| evenrowbackgroundimage || Specify an image (content for a CSS background-image tag) for the even card rows || none || Per-Line<br />
|-<br />
| executionlimit || Maximum number of script lines the interpreter will try to execute. This prevents "infinite loop" sandbox crashes || 40000 || Global<br />
|-<br />
| hideCard || If set to any non-default value, the entire card output will be suppressed || 0 || Global<br />
|-<br />
| 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<br />
|-<br />
| 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<br />
|-<br />
| lineheight || Vertical size of each line on the output card || normal || Per-Line<br />
|-<br />
| nominmaxhighlight || If set to anything other than "0", rolls will not display crit/fumble/mixed highlight colors. || 0 || Per-Line<br />
|-<br />
| norollhighlight || If set to anything other than "0", rolls will not be formatted (plain numbers) but will still get a tooltip with details ('''''v1.3.6b+''''') || 0 || Per-Line<br />
|-<br />
| oddRowBackground || Hex code for the background color for even rows || #d0e4f5 || Per-Line <br />
|-<br />
| oddRowFontColor || Hex code for the text color for odd rows || #000000 || Per-Line<br />
|-<br />
| oddrowbackgroundimage || Specify an image (content for a CSS background-image tag) for the odd crd rows || none || Per-Line<br />
|-<br />
| reentrant || Used to name a script for rentrant button use || 0 || Global<br />
|-<br />
| 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)0 || Global<br />
|-<br />
| rollhilightlineheight || Determines the height of the hilight box placed around roll results ('''''1.4.2+''''') || 1.0em || Per-Line<br />
|-<br />
| roundUp || If set to a non-default value, integer division will round up instead of down || 0 || Per-Line<br />
|-<br />
| showfromfornonwhispers || If set to a non-zero value, will include the sender on cards that aren't whispered || 0 || Global<br />
|-<br />
| 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<br />
|-<br />
| subtitleFontColor || Color of the text in the subtitle areas || #FFFFFF || Global<br />
|-<br />
| subtitleFontFace || Name of the font used on the subtitle sections || Tahoma || Global<br />
|-<br />
| subtitleFontSize || Size of the subtitle font || 13px || Global<br />
|-<br />
| subtitleSeperator || The character(s) that will be placed between leftsub and rightsub || <nowiki>&#x2666</nowiki>; || Global<br />
|-<br />
| tableBorderRadius || CSS specifier for how rounded the borders of the output card are. Use "0px;" for square borders || 6px; || Global<br />
|-<br />
| tableShadow || CSS specifier for the drop shadow under the output card || 5px 3px 3px 0px #aaa; || Global<br />
|-<br />
| tablebgcolor || Background color of the whole card. '''''Normally not visible''''' || #EEEEEE || Global<br />
|-<br />
| tableborder || Color of the border that surrounds the whole card || 2px solid #000000; || Global<br />
|-<br />
| 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<br />
|-<br />
| timezone || IANA Specifier for the local time zone, used in system/date functions || merica/New_York || Per-Line<br />
|-<br />
| title || Text displayed in the title area of the card || ScriptCards || Global<br />
|-<br />
| titleCardBackground || A hex color code representing the background color of the title area. || #1c6ea4 || Global<br />
|-<br />
| titleFontColor || Color of the text on the card title || #FFFFFF || Global<br />
|-<br />
| titleFontFace || Name of the font used on the title area || Contrail One || Global<br />
|-<br />
| titleFontLineHeight || Line spacing on the title area || 1.2em || Global<br />
|-<br />
| titleFontSize || Size of the title font || 1.2em || Global<br />
|-<br />
| titlecardbackgroundimage || Specify an image (content for a CSS background-image tag) for the title card area || none || Global<br />
|-<br />
| titlecardbottomborder || Border CSS specifier for the bottom of the title card area || 2px solid #444444; || Global<br />
|-<br />
| titlecardgradient || If set to non-zero value, will place a vertical gradient on the title card area || 0 || Global<br />
|-<br />
| usehollowdice || If set to a non-zero value, the hollow/outline versions of the dice fonts will be used || 0 || Per-Line<br />
|-<br />
| whisper|| Comma separated list of who to whisper the output to. Use "gm" for [[GM|GMs]] and "self" for the sender || none || Global|}<br />
|}<br />
<br />
''Setting Lines do not produce output lines on the card''<br />
<br />
=== Direct Output (--+) ===<br />
<br />
A direct output line display 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.<br />
<br />
Examples of Direct Output lines:<br />
<pre><br />
--+Hello|World<br />
--+Attack|The monster rolls [$Attack] to hit!<br />
--+Damage|@{target|token_name} is hit for [$Damage] [#3333AA][b]frost[/b][/#] damage.<br />
</pre><br />
<br />
Direct Output lines support inline formatting, roll variable replacement, character attribute references, and procedure variables.<br />
<br />
=== GM Output (--*) ===<br />
<br />
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. <br />
<br />
Example:<br />
<pre><br />
--+PlayerLine|This line is shown on the public card<br />
--*GMLine|This line will only be shown to GMs, on a separate card.<br />
</pre><br />
<br />
=== Roll Variable Assignment (--=) ===<br />
<br />
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.<br />
<br />
'''''All components of a roll equation should be separated with spaces.'''''<br />
<br />
Examples:<br />
<pre><br />
--=MissileDamage|1d4 + 1<br />
--=Attack|1d20 + @{selected|strength_mod} [STR] + @{selected|pb} [PROF]<br />
</pre><br />
<br />
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. Text enclosed in square brackets ([]) is considered "flavor text" and will be added to the result text but does not impact the roll result.<br />
<br />
The following dice formats are supported:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Format Pattern !! Example !! Description<br />
|-<br />
| XdY || 3d8 || Simple format. Roll a Y-sided die X times<br />
|-<br />
| XdYkhZ || 2d20kh1 || Roll Y-sided die X times and keep the highest Z number of dice<br />
|-<br />
| XdYklZ || 4d6kl3 || Roll Y-sided die X times and keep the lowest Z number of dice <br />
|-<br />
| XdY>Z || 5d6>3 || Roll Y-sided die X times and count a 1 for each roll greater than Z <br />
|-<br />
| XdY<Z || 5d6<3 || Roll Y-sided die X times and count a 1 for each roll less than Z <br />
|}<br />
<br />
'''''Note: The dice formulae below are supported in the development version of ScriptCards and will be merged with the table above when activated on OneClick'''''<br />
::{| class="wikitable"<br />
|-<br />
! Format Pattern !! Example !! Description<br />
|-<br />
| 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<br />
|-<br />
| 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<br />
|-<br />
| 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)<br />
|-<br />
| 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<br />
|}<br />
<br />
The following operators are supported in a roll equation:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Operator !! Operation<br />
|-<br />
| + || Addition <br />
|-<br />
| - || Subtraction <br />
|-<br />
| * || Multiplication <br />
|-<br />
| / || Division <br />
|-<br />
| \ || Integer Division (Rounds down) <br />
|-<br />
| % || Modulo (Remainder of Divison)<br />
|}<br />
<br />
Roll Variables can be accessed at any time after they have been created by using the [$VariableName] format, with the following optional modifiers:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Modifier !! Meaning<br />
|-<br />
| No modifier || In a Direct Output Line (<nowiki>--+</nowiki>) 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<br />
|-<br />
| .Total || The end result of the roll equation as an unformatted number <br />
|-<br />
| .Base || The cumulative result of any dice rolled in the Roll Text (Numeric modifiers are not included) <br />
|-<br />
| .Ones || The number of dice in the roll that came up as 1s <br />
|-<br />
| .Aces || The number of dice in the roll that came up as the maximum number on the die <br />
|-<br />
| .Odds || The number of dice in the roll that came up with an odd number <br />
|-<br />
| .Evens || The number of dice in the roll that came up with an even number <br />
|-<br />
| .RollText || The raw text of the roll that was use to generate the results <br />
|-<br />
| .Text || A text representation of the results of the roll, including the numbers rolled for each die <br />
|-<br />
| .tableEntryText || The text portion of the result of a table roll<br />
|-<br />
| .tableEntryImgURL || The image source portion of the result of a table roll<br />
|-<br />
| .tableEntryValue || Numeric value of tableEntryText (via parseInt). If a non-numeric value, will be 0<br />
|-<br />
| .Raw || The total numeric result without any formatting, even if placed somewhere formatting would normally be done. <br />
|}<br />
<br />
Examples:<br />
<pre><br />
--+Total Damage|[$MissileDamage.Total] (roll was 1d4+1)<br />
--+Base Damage|[$MissileDamage.Base] (without the +1)<br />
--=Attack|1d20 + @{selected|strength_mod} [STR] + @{selected|pb} [PROF] + [$BlessBonus] [Bless]<br />
</pre><br />
<br />
In this case, 1d4 will be rolled and stored in “BlessBonus”, which can then be used in the Attack line.<br />
<br />
'''''Mathematical Functions in Roll Expressions '''''<br />
<br />
The ScriptCards roll parser works from left to right, always maintaining a current value and applying whatever comes next to the total. The following in-line functions to the roll parser. These are:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Expression !! Meaning<br />
|-<br />
| {ABS} || Absolute Value<br />
|-<br />
| {CEIL} || Ceiling value (round up to the next whole number)<br />
|-<br />
| {FLOOR} || Floor value (round down to the next whole number)<br />
|-<br />
| {ROUND} || Round value (round up if the decimal portion is greater than 0.5, otherwise round down)<br />
|-<br />
| {NEGATE} || Multiply the value by negative one.<br />
|-<br />
| {SQRT} || Take the square root of the running value. ('''''1.4.1+''''')<br />
|-<br />
| {SQUARE} || Square the running value. ('''''1.4.2+''''')<br />
|-<br />
| {CUBEROOT} || Take the cube root of the running value. ('''''1.4.2+''''')<br />
|-<br />
| {CUBE} || Cube the running value. ('''''1.4.2+''''')<br />
|-<br />
| {SIN} || Return the SIN of running value. ('''''1.4.2+''''')<br />
|-<br />
| {COS} || Return the COS of running value. ('''''1.4.2+''''')<br />
|-<br />
| {TAN} || Return the TAN of running value. ('''''1.4.2+''''')<br />
|-<br />
| {ASIN} || Return the ASIN of running value. ('''''1.4.2+''''')<br />
|-<br />
| {ACOS} || Return the ACOS of running value. ('''''1.4.2+''''')<br />
|-<br />
| {ATAN} || Return the ATAN of running value. ('''''1.4.2+''''')<br />
|}<br />
<br />
<br />
'''''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 <nowiki>[[ ]]</nowiki> 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.<br />
<br />
'''''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.<br />
<br />
'''Rolling on Rollable Tables'''<br />
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.<br />
<br />
''Roll Variable Lines do not produce output lines on the card.''<br />
<br />
=== String Variable Assignment (--&) ===<br />
<br />
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:<br />
<br />
<pre><br />
--&MyText|Hello<br />
</pre><br />
<br />
Here, we assign the text "Hello" to the string variable named MyText. You can also append text to a string variable by prefixing the content with a + sign:<br />
<br />
<pre><br />
--&MyText|+ World<br />
</pre><br />
<br />
If run after the statement above, MyText will now contain "Hello World".<br />
<br />
String variables can be referenced using the syntax [&variablename]<br />
<br />
=== Call API (--@) ===<br />
<br />
ScriptCards can use a Call API instruction to execute other API commands. The Tag contains the API 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 API command is executed.<br />
<br />
Examples:<br />
<pre><br />
--@eh|list<br />
--@alter|_target|@{target|token_id} _bar|3 _amount|-[$Damage]<br />
</pre><br />
<br />
In the first example above, the command <code>!eh list</code> will be executed, calling [[EncounterHelper]]. In the second, {{fpl|1216260/ AlterBars}} is called to modify a token's Bar 3 value.<br />
<br />
'''''Note:''''' When ScriptCards (or any API script) runs other API 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).<br />
<br />
See [[API:Script Index]] for more options.<br />
<br />
=== Branch Label (--:) ===<br />
<br />
A branch label defines a line in your code that can be reached by one of the branching instructions (<nowiki>--^</nowiki>, <nowiki>--></nowiki>, or <nowiki>--?</nowiki>). The Tag serves as the label name, and must be unique on the card.<br />
<br />
The vertical bar (|) separator must be present, but the content portion of the line is unused and can be treated as a comment.<br />
<br />
Examples:<br />
<pre><br />
--:MyLoop|<br />
--:CriticalHit|Will jump here if we roll a critical hit!<br />
</pre><br />
<br />
''A Branch Label line does not produce an output line on the card.''<br />
<br />
=== Branch (--^) === <br />
<br />
A Branch line 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.<br />
<br />
Examples:<br />
<pre><br />
--^MyLoop|Jumps to MyLoop<br />
--^SkipCrit|We didn't crit, so skip the Crit code<br />
</pre><br />
<br />
''A Branch line does not produce an output line on the card.''<br />
<br />
=== Call Procedure (-->) ===<br />
<br />
Similar to a branch, a Call Procedure (sometimes knows 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 (<nowiki>--<</nowiki>) 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 (;).<br />
<br />
Examples:<br />
<pre><br />
-->FixFormat|#3333FF;#999999<br />
</pre><br />
<br />
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%].<br />
<br />
=== Return (--<) ===<br />
<br />
A return instruction marks the end of a Gosub procedure. 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.<br />
<br />
Examples:<br />
<pre><br />
--<|<br />
--<|End of MySub<br />
</pre><br />
<br />
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.<br />
<br />
=== Conditional Statement (--?) ===<br />
<br />
A conditional statement contains some equation in the Tag that will be evaluated. '''''If any part of the comparison can/does contain a space, it needs to be surrounded by double quotes'''''<br />
<br />
Based on the true/false result of the evaluation, one of two execution paths will be taken. These execution paths are detailed in the content section of the statement. The "if true" path is specified first (directly after the vertical bar), and the "if false" path is specified after it, also separated by a vertical bar.<br />
<br />
Example:<br />
<pre><br />
--?[$AttackRoll.Total] -ge [$TargetAC]|Hit|Miss<br />
</pre><br />
<br />
'''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.'''<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Branch Format !! Meaning<br />
|-<br />
| Label || If just a label is specified, execution will branch to that label when the comparison is matched.<br />
|-<br />
| >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 <br />
|-<br />
| =VariableName || The roll variable "VariableName" will be assigned the value following a semicolon (ex: --?1 -eq 1|=Roll;1d20)<br />
|-<br />
| &VariableName || The string variable "VariableName" will be assigned the value following a semicolon (ex: --?1 -eq 1|&Result;Hit|&Result;Miss)<br />
|-<br />
| % or %! || The current for...next loop will perform the "next" action (%) or will break out (%!) <br />
|-<br />
| [ || Code block (see below)<br />
|}<br />
<br />
Examples:<br />
<pre><br />
--?[$AttackRoll.Base] -eq 20|CriticalHit<br />
--?[$AttackRoll.Base] -eq 1|>Fumble;@{selected|dexterity_mod}<br />
--?"@{target|npc_type}" -inc "undead"|&MonsterType;Undead|&MonsterType;Not Undead<br />
--?[$Attack.Total] >= [$ArmorClass]|>Hit|>Miss<br />
</pre><br />
<br />
In the first example, if the Base value of AttackRoll is a 20 (natural 20 on the die) execution will branch to the CriticalHit label.<br />
<br />
In the second example, 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%].<br />
<br />
The third example looks for the word "undead" in the npc_type attribute of the targeted character. If it exists in the text, the MonsterType string variable will be set to "Undead", otherwise it will be set to "Not Undead". <br />
<br />
The final example would call 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.<br />
<br />
''Text that does/may contain a space should be enclosed in double quotes.''<br />
<br />
The following comparison operators are available:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Comparator !! Meaning<br />
|-<br />
| -eq || Equal To <br />
|-<br />
| -eqi || Case insensitive Equal To <br />
|-<br />
| -ne || Not Equal To <br />
|-<br />
| -nei || Case insensitive Not Equal To <br />
|-<br />
| -gt || Greater Than <br />
|-<br />
| -ge || Greater Than or Equal To <br />
|-<br />
| -lt || Less Than <br />
|-<br />
| -le || Less Than or Equal To <br />
|-<br />
| -inc || Includes (text strings). <br />
|-<br />
| -ninc || Does Not Include (text strings). <br />
|}<br />
<br />
Multi-part conditionals are supported with -and and -or as separators. For example:<br />
<br />
<pre><br />
--?[$Attack.Total] -ge @{target|npc_ac} -and [$Attack.Base] -ne 20|HitButNotCrit<br />
</pre><br />
<br />
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):<br />
<br />
true AND false OR true<br />
<br />
Will be evaluated as true. The first two (true and false) will be false, but then false OR true will be true.<br />
<br />
Conversely:<br />
<br />
true or false and false<br />
<br />
Will be false, because the first true and false will evaluate to true, and then true and false will be false.<br />
<br />
'''CODE BLOCKS'''<br />
<br />
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.<br />
<br />
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:<br />
<br />
<pre><br />
!script {{<br />
--=Roll|1d2<br />
--+Roll|[$Roll]<br />
--?[$Roll.Total] -eq 2|[<br />
--&Value|Yep!<br />
--+|We are inside the TRUE portion of the block<br />
--]|[<br />
--&Value|Nope<br />
--+|We are inside the FALSE portion of the block<br />
--]|<br />
--+After|the blocks!<br />
--+Value|[&Value]<br />
}}<br />
</pre><br />
<br />
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 --]|. <br />
<br />
At this time, blocks cannot be nested, and can only be created as part of a conditional (--[ is not a valid statement type)<br />
<br />
''A conditional statement does not produce a line of output on the card.''<br />
<br />
=== Case Statement (--c) ===<br />
<br />
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 (:). Each match condition includes a branch label that will be used if the test value matches the item. 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:<br />
<br />
<pre><br />
!script {{<br />
--#title|Case Statement Testing<br />
--=Roll|1d4<br />
--C[$Roll.Total]|1:>One;[$Roll]|2:>Two;[$Roll]|3:>Three;[$Roll]|4:>Four;[$Roll]<br />
--X|<br />
<br />
--:One| --+Value|was One ([%1%]) --<|<br />
--:Two| --+Value|was Two ([%1%]) --<|<br />
--:Three| --+Value|was Three ([%1%]) --<|<br />
--:Four| --+Value|was Four ([%1%]) --<|<br />
}}<br />
</pre><br />
<br />
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 variable as a parameter.<br />
<br />
=== Save and Load (--s and --l) ===<br />
<br />
This statement pair is used to either store (--s) or load (--l) data from persistent storage. Items stored in persistent storage remain between card rolls and between Roll20 sessions. There are two types of data that can be stored: settings and roll variables. <br />
<br />
Examples:<br />
<br />
<pre><br />
--Ssettings|GreenStyle<br />
--Srollvariables|FirstCardVars<br />
</pre><br />
<br />
In this case, the tag for the statement determines what type of item is being saved (settings or rollvariables). When saving settings, all non-default settings are written to the named setting storage value. When Roll Variables are saved, all variables that currently exist will be saved to the named storage value.<br />
<br />
Loading stored items simply requires the same command with the --l statement type:<br />
<br />
<pre><br />
--Lsettings|GreenStyle<br />
--Lrollvariables|FirstCardVars<br />
</pre><br />
<br />
When loading settings, all stored settings will be applied to the current card settings. You can override settings by changing them after the load.<br />
<br />
When loading roll variables, the saved variables will be added to (or overwrite if they have the same name) any variables on the current card. This means it is safe to create roll variables before the load statement.<br />
<br />
'''Practical Uses'''<br />
The major intended use of persistent storage is for storing card formats for use in later scripts. For example, the following script:<br />
<br />
<pre><br />
!scriptcard {{<br />
--#titlecardbackground|#22CC22<br />
--#oddrowbackground|#cceecc<br />
--#evenrowbackground|#99ee99<br />
--Ssettings|@{selected|token_name}<br />
}}<br />
</pre><br />
<br />
Would save the titlecardbackground, oddrowbackground, and evenrowbackground settings to a saved list named after the selected token's name. When creating cards for that token to run later, you could include the line:<br />
<br />
<pre><br />
--Lsettings|@{selected|token_name}<br />
</pre><br />
<br />
To load all of the settings at once. By creating these setting sets for each character, you can specify a different color scheme for each character that can then be used in cards with a single formatting line.<br />
<br />
There is a supplemental ! command added to support saved settings:<br />
<br />
<pre><br />
!sc-liststoredsettings<br />
</pre><br />
<br />
Will produce a list of all stored setting names, with buttons to list the setting values stored in each group and a button to delete groups as needed.<br />
<br />
=== Visual Effects (--v) ===<br />
<br />
The --v statement can be used to create visual effects on the tabletop. The tag portion of the statement can be either "token" or "betweentokens". The content portion of the statement contains the required parameters for the effect generation, separated by spaces. If the effect is "none", no effect will be played. If any other value that doesn't match a Roll20 effect name will result in a burst-fire effect.<br />
<br />
For "token" effects, the parameters are the token id for the token the effect happens on, followed by the effect specifier.<br />
<br />
Example:<br />
<pre><br />
--vtoken|@{selected|token_id} burst-fire<br />
</pre><br />
<br />
For "betweentoken" effects, the parameters are the source token id, the target token id, and the effect specifier.<br />
<br />
Example:<br />
<pre><br />
--vbetweentokens|@{selected|token_id} @{target|token_id} beam-magic<br />
</pre><br />
<br />
'''''Version 1.2.8+'''''<br />
<br />
An additional effect specifier, "point" is available in 1.2.8+. This specifier allows you to create a visual effect at a designated X/Y pixel coordinate. Future updates will add custom-vfx support to this option. The parameters are the X and Y coordinates and the effect descriptor. As of version 1.2.9, you can also use custom effect specifiers with Point effects:<br />
<br />
<pre><br />
--vpoint|150 200 burst-fire<br />
</pre><br />
<br />
=== Echo to Chat (--e) ===<br />
<br />
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.<br />
<br />
Example:<br />
<pre><br />
--eThe Ghost|/em hovers around @{selected|character_name}... BOO!<br />
</pre><br />
<br />
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).<br />
<br />
'''''Whispering'''''<br />
<br />
You can use the echo statement to send a whisper, but there's a trick to it. If you execute this code here:<br />
<br />
<pre><br />
--eThe Ghost|/w ExamplePlayerName Boo.<br />
</pre><br />
<br />
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.<br />
<br />
So, in conclusion, it's best to use something like this when you're sending a whisper:<br />
<br />
<pre><br />
!script {{<br />
--#hidecard|1<br />
--&sender|The Ghost<br />
--&receiver|ExamplePlayerName<br />
--&message|Boo.<br />
--e[&sender]|/w [&receiver] [&message]<br />
--eScriptCards|/w gm **Whispered from [&sender] to [&receiver]:** [&message] <br />
}}<br />
</pre><br />
<br />
This will ensure that the message appears in your chat feed as well.<br />
<br />
=== Repeating Section Access (--R) ===<br />
<br />
ScriptCards (as of v0.0.13) supports accessing repeating section rows on a character sheet (for example: the attacks, the items, and the repeating resources) with the --R statement type. <br />
<br />
There are three basic commands you can use with --R, and they are specified by the tag used:<br />
<br />
'''''find'''''<br />
<br />
An Rfind statement is used to search through a repeating field. Here is the general form of such a statement.<br />
<br />
<pre><br />
--Rfind|characterid;EntryName;SectionPrefix;SearchField<br />
</pre><br />
<br />
This is the most direct way to access a repeating section row. Supplying the character ID, followed by what you are looking for (Greatsword, for example), followed by the character sheet's section prefix (repeating_attack), followed by the field to check what you are searching for (atkname) will load the matching section (if found) into the script parsers memory. For example:<br />
<br />
<pre><br />
--Rfind|@{selected|character_id};Greatsword;repeating_attack;atkname<br />
</pre><br />
<br />
Will look at the character's "repeating_attack" section for an entry with an atkname value equal to "Greatsword". Similarly:<br />
<br />
<pre><br />
--Rfind|@{selected|character_id};Bite;repeating_npcaction;name<br />
</pre><br />
<br />
Will look for a "Bite" action on an NPC's action list.<br />
<br />
'''''first'''''<br />
<br />
<pre><br />
--Rfirst|characterid;section prefix<br />
</pre><br />
<br />
This form of the --R command will look at all of the entries in the specified repeating section and load the first one into memory:<br />
<br />
<pre><br />
--Rfirst|@{selected|character_id};repeating_attack<br />
</pre><br />
<br />
Would load the character's first "repeating_attack" row into memory.<br />
<br />
'''''next'''''<br />
<br />
<pre><br />
--Rnext|<br />
</pre><br />
<br />
No parameters are required for --Rnext, which loads the next entry in the list that was obtained with "first" into memory.<br />
<br />
'''''The section prefixes for the 5E by roll20 character sheet'''''<br />
<br />
Can somebody please add a list of them here?<br />
<br />
'''''Additional information'''''<br />
<br />
However a row is obtained, it will be parsed to replace any attribute references (ie, @{level}) with the corresponding character attribute.<br />
<br />
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".<br />
<br />
You can reference repeating attribute data using the syntax [*R:attributename] syntax (similar to referencing standard character attributes).<br />
<br />
Here are some examples:<br />
<br />
Display the details of the "Greatsword" PC attack:<br />
<br />
<pre><br />
!script {{<br />
--Rfind|@{selected|character_id};Greatsword;repeating_attack;atkname<br />
--+Attack Name|[*R:atkname]<br />
--+Base Damage|[*R:dmgbase]<br />
}}<br />
</pre><br />
<br />
[[File:Scriptcards repeating greatsword.png|Repeating Greatsword Attack]]<br />
<br />
List all of the actions an NPC can take (just actions, not legendary, etc.)<br />
<br />
<pre><br />
!script {{<br />
--#title|NPC Actions<br />
--#leftsub|@{selected|token_name}<br />
--Rfirst|@{selected|character_id};repeating_npcaction<br />
--:DisplayLoop|<br />
--?"[*R:name]" -eq NoRepeatingAttributeLoaded|Done<br />
--+Action:|[*R:name] [*R:attack_damage] [*R:attack_damagetype]<br />
--?"[*R:attack_damage2]" -eq ""|NoSecondaryDamage<br />
--+ |[*R:attack_damage2] [*R:attack_damagetype2]<br />
--:NoSecondaryDamage|<br />
--Rnext|<br />
-->DisplayLoop| <br />
--:Done|<br />
}}<br />
</pre><br />
<br />
[[File:Scriptcards repeating npcactions.png]]<br />
<br />
In the script above, we get the "first" repeating_npcaction and display information about it. We then execute "next" and repeat until we run into "NoRepeatingAttributeLoaded".<br />
<br />
'''''Special debugging command: dump'''''<br />
<pre><br />
--Rdump|<br />
</pre><br />
<br />
The "dump" command will list all of the attributes ScriptCards knows about for the currently loaded repeating row to the API Console Log.<br />
<br />
=== Assign Variable to Built-In Function (--~) ===<br />
<br />
ScriptCards has the ability to run a function built into the API script and return the results to a variable. Some functions return roll variables, while others return strings. See the function table below for details. The format is:<br />
<br />
--~VariableName|function;param1;param2;param3;...<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Function Name !! Parameters !! Description<br />
|-<br />
| distance || token_A_ID;token_B_ID || Calculate the Chebyshev distance in grid units between two tokens. This is the measurement scheme D&D 4E/5E use for diagonal distance measurement<br />
|-<br />
| euclideandistance || token_A_ID;token_B_ID || Calculate the Euclidean distance between two tokens. This is essentially the Pythagorean theorem in action. Returns the result in grid units.<br />
|-<br />
| euclideanpixel || token_A_ID;token_B_ID || Calculate the Euclidean distance between two tokens and returns the result is pixels instead of grid units. <br />
|-<br />
| euclideanlong || token_A_ID;token_B_ID || 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 is calculated instead of before. More accurate over long distances. <br />
|-<br />
| manhattandistance || token_A_ID;token_B_ID || Also called "taxicabdistance" (which is an acceptable function name), this measures to how-many-over, how-many-up/down distance, disallowing diagonal movement.<br />
|-<br />
| getselected || none || 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 the first selected token, VariableName2 the second, etc.<br />
|}<br />
<br />
'''''Functions with Sub Functions'''''<br />
<br />
Most ScriptCards functions are grouped into set as sub functions. The table below lists the major functions and their sub functions.<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Function Name !! Sub Function !! Parameters !! Return Type !! Description<br />
|-<br />
| array || define || arrayname;value1;value2;... || none || Creates an array called "arrayname" and adds value1, value2, etc. to the array<br />
|-<br />
| array || sort || arrayname || none || Sorts the specified array in place in ascending order<br />
|-<br />
| array || add || arrayname;value1;value2;... || none || Adds value1, value2, ... to the existing array "arrayname"<br />
|-<br />
| array || remove || arrayname;value1;value2;... || none || Removes value1, value2, ... from the existing array "arrayname". Resets the array index to 0.<br />
|-<br />
| array || replace || arrayname;currentvalue;newvalue || none || Replaces all occurrences of "currentvalue" in "arayname" with "newvalue"<br />
|-<br />
| array || setatindex || arrayname;index;newvalue || none || Replaces the array item at index "index" with "newvalue"<br />
|-<br />
| array || getindex || arrayname || stringVariable || Retrieves the current index in "arrayname" and stores it in the supplied string variable<br />
|-<br />
| array || setindex || arrayname;newindex || none || Sets the current index in array "arrayname" to "newindex"<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| array || removeat || arrayname;indexposition || none || Removes the item at index "indexposition" from "arrayname". Resets the current array index to 0.<br />
|-<br />
| array || indexof || arrayname;searchvalue || stringVariable || Searches the array "arrayname" for and item with the value of "searchvalue" and, if found, returns the index of the first matching value or "ArrayError" if not found<br />
|-<br />
| array || getlength || arrayname || stringVariable || Returns the number of items in array "arrayname"<br />
|-<br />
| array || pagetokens || arrayname;tokenid;(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. 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.)<br />
|-<br />
| 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.<br />
|-<br />
| array || stringify || arrayname || stringVariable || Returns all of the items in "arrayname" as a string separated by semicolons (;)<br />
|-<br />
| array || fromstring || arrayname || delimiter;string || Creates an array from "string", splitting "string" on "delimiter" to separate the items<br />
|-<br />
| array || statusmarkers|| arrayname;tokenid || none|| Creates an array (arrayname) of the active statusmarkers (sometimes called Token Markers) for the specified tokenid<br />
|-<br />
| math || angle || math;angle;tokenid;tokenid|| rollVariable || Calculates the angle between two tokens and returns the value in degrees<br />
|-<br />
| math || ceil || math;ceil;value || rollVariable || Rounds '''value''' up to the next integer, dropping any decimal portion of the number<br />
|-<br />
| math || clamp || math;clamp;value;lowerBound;upperBound || rollVariable || Returns '''value''', but restricted to the range of '''loweBound''' and '''upperBound'''.<br />
|-<br />
| math || floor || math;floor;value || rollVariable || Rounds '''value''' down, dropping any decimal portion of the number<br />
|-<br />
| math || max || math;max;valueA;valueB || rollVariable || Returns the larger of '''valueA''' vs '''valueB'''<br />
|-<br />
| math || min || math;min;valueA;valueB || rollVariable || Returns the smaller of '''valueA''' vs '''valueB'''<br />
|-<br />
| math || round || math;round;value || rollVariable || Rounds '''value''' to the nearest integer<br />
|-<br />
| string || length || string;length;stringValue || rollVariable || Returns the length of '''stringValue''' in characters<br />
|-<br />
| string || before || string;before;searchText;stringValue || stringVariable || Searches '''stringValue''' for '''searchText''' and returns the portion of '''stringValue''' prior to that text<br />
|-<br />
| string || after || string;after;searchText;stringValue || stringVariable || Searches '''stringValue''' for '''searchText''' and returns the portion of '''stringValue''' after that text<br />
|-<br />
| string || left || string;left;count;stringValue || stringVariable || Returns the leftmost '''count''' characters of '''stringValue'''<br />
|-<br />
| string || right || string;right;count;stringValue || stringVariable || Returns the rightmost '''count''' characters of '''stringValue'''<br />
|-<br />
| string || replace || string;replace;searchText;replaceText;stringValue || stringVariable || Replaces '''searchText''' in '''stringValue''' with '''replaceText''' and returns the resulting string<br />
|-<br />
| string || replaceall || string;replace;searchText;replaceText;stringValue || stringVariable || Replaces all intances of '''searchText''' in '''stringValue''' with '''replaceText''' and returns the resulting string '''''Requires 1.2.9+'''''<br />
|-<br />
| string || trim || string;trim;stringValue || stringVariable || Removes leading and trailing spaces from stringValue and returns the result. <br />
|-<br />
| string || substring || string;substring;start;count;stringValue || stringVariable || Returns '''count''' characters starting at '''start''' from '''stringValue'''<br />
|-<br />
| 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.<br />
|-<br />
| string || tolowercase || string;tolowercase;stringValue || stringVariable || Converts the passed string to lower case and assigns to the passed variable name. <br />
|-<br />
| string || touppercase || string || stringVariable || Converts the passed string to upper case and assigns to the passed variable name. <br />
|-<br />
| 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. <br />
|-<br />
| 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.<br />
|-<br />
| 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'''.<br />
|-<br />
| turnorder || clear || none || none || Clears all entries from the {{Turn Tracker}}/Initiative<br />
|-<br />
| turnorder || addtoken || tokenid;trackervalue || none || Adds the token represented by "tokenid" to the initiative tracker with an initiavie value of "trackervalue"<br />
|-<br />
| turnorder || replacetoken || tokenid;trackervalue || none || Replaces the token represented by "tokenid" in the initiative tracker with an initiavie value of "trackervalue". Will add the token if it doesn't exist in the tracker.<br />
|-<br />
| turnorder || removetoken || tokenid || none || Removes the token represented by "tokenid" from the initiative tracker if it exists<br />
|-<br />
| turnorder || addcustom || textlabel;trackervalue || none || Add a custom text entry to the {{Turn Tracker}}/Initiative named "textlabel" with an initiative value of "trackervalue"<br />
|-<br />
| system || date || getdatetime || stringVariable || Returns the date time in the active timezone (see settings) <br />
|-<br />
| system || date || getdate || stringVariable || Returns the date in the active timezone (see settings) <br />
|-<br />
| system || date || gettime || stringVariable || Returns the time in the active timezone (see settings)<br />
|-<br />
| system || dumpvariables || "rolls", "string", or "array" || none || Dumps all of the defined variables of the indicated type to the console log<br />
|-<br />
| system || findability || system;findability;charactername;abilityname || stringVariable || Returns the object ID of the ability on the indicated character or "AbilityNotFound"<br />
|-<br />
|}<br />
<br />
Examples:<br />
<br />
<pre><br />
--~HowFarAway|distance;@{selected|token_id};@{target|token_id}<br />
</pre><br />
<br />
Returns the distance (Chebyshev) between the selected and target tokens and stores it in "HowFarAway".<br />
<br />
<pre><br />
--SelectedDudes|getselected<br />
</pre><br />
<br />
If 5 tokens were selected, 6 variables would be created: SelectedDudesCount (with a value of 5), SelectedDudes1, SelectedDudes2, SelectedDudes3, SelectedDudes4, SelectedDudes5.<br />
<br />
=== Information Request (--i) ===<br />
<br />
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.<br />
<br />
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.<br />
<br />
After the user has clicked the button and responded to the requests, ScriptCards will resume processing the script from where it left off.<br />
<br />
Here is an example “i” line:<br />
<br />
<pre><br />
--IScriptCards needs additional information to continue;Click to select a target and provide information|t;MyNewTarget;Missile1Target||q;MyNameIs;What is your name?<br />
</pre><br />
<br />
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.<br />
<br />
Supported information request types are “t” for target token, and “q” for query.<br />
<br />
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).<br />
<br />
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:<br />
<br />
<pre><br />
q;UserName;What is your name?|Fred|Bob|Sally|Nancy<br />
</pre><br />
<br />
Would have a dropdown menu with four choices.<br />
<br />
== Inline Formatting ==<br />
<br />
Inline formatting is processed on Direct Output lines only (--+ lines) and the following inline format markup is available:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Formatting Tags !! Description<br />
|-<br />
| [b]..[/b] || Bold the text between the markers <br />
|-<br />
| [i]..[/i] || Italicize the text between the markers <br />
|-<br />
| [u]..[/u] || Underline the text between the markers <br />
|-<br />
| [s]..[/s] || Strike-Thru the text between the markers <br />
|-<br />
| [c]..[/c] || Center alignment <br />
|-<br />
| [l]..[/l] || Left alignment <br />
|-<br />
| [r]..[/r] || Right alignment <br />
|-<br />
| [j]..[/j] || Full justification alignment <br />
|-<br />
| [#xxx]..[/#] or [#xxxxxx]..[/#] || Use a 3 or 6 digit hex code to colorize the text between the markers <br />
|-<br />
| [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, <code>[img width=128 height=128]</code> )<br />
|-<br />
| [button]caption::action[/button] || Create a button with the label "caption" that performs the action defined by "action". <br />
|-<br />
| [t] || Converted to HTML table tag. Text after the "t" will be included inside the tag (width, border, etc)<br />
|-<br />
| [/t] || Converted to HTML close table tag.<br />
|-<br />
| [tr] || Converted to HTML table row tag. Text after the "tr" will be included inside the tag<br />
|-<br />
| [/tr] || Converted to HTML close table row tag.<br />
|-<br />
| [td] || Converted to HTML table cell tag. Text after the "tr" will be included inside the tag<br />
|-<br />
| [/td] || Converted to HTML close table cell tag.<br />
|}<br />
<br />
== Variables ==<br />
<br />
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. While it is possible to assign both a string and a roll variable the same name, doing so will likely result in confusion when looking at the script later, so it is not recommended.<br />
<br />
String Variables are assigned with the --& statement and are referenced using [&variableName] notation.<br />
<br />
Roll Variables are assigned with the --= statement, and the assignment value is always processed by the ScriptCards Roll Processor (resolves dice rolls, etc.)<br />
<br />
There are a handful of variables assigned automatically when a ScriptCard is executed. These are all string variables, and are:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Variable !! Value<br />
|-<br />
| SendingPlayerID || Contains the object ID of the player that sent the macro<br />
|-<br />
| SendingPlayerName || Contains the display name of the player<br />
|-<br />
| SendingPlayerColor || Contains the color code associated with the player<br />
|-<br />
| SendingPlayerSpeakingAs || The contents of the "Speaking As" dropdown window<br />
|-<br />
| SendingPlayerIsGM || Contains 1 if the player is a GM, and 0 if the player is NOT a GM<br />
|}<br />
<br />
== Arrays ==<br />
<br />
Arrays are a special type of variable, and are managed by the function (<nowiki>--~</nowiki> command). All of the array function commands follow the same pattern:<br />
<br />
<pre>--~variableName|array;subcommand;arrayname;param1;param2;param3;...</pre><br />
<br />
Not all array commands return anything to "variableName". The function table above will specify the return type of the command if any.<br />
<br />
There are a couple of different ways to create an array:<br />
<br />
The '''define''' array subcommand creates (or recreates) an array and assigns it values - one for each included parameter after the array name. For example:<br />
<br />
<pre>--~|array;define;Fruits;mango;peach;strawberry;apricot;banana;apple</pre><br />
<br />
will create an array called '''Fruits''' with 6 elements in the order listed in the command (mango, peach, etc.)<br />
<br />
You can also use two other subcommands to create arrays based on tokens:<br />
<br />
<pre>--~Count|array;pagetokens;Everybondy;@{selected|token_id}</pre><br />
<br />
and<br />
<br />
<pre>--~Count|array;selectedtokens;Selected</pre><br />
<br />
In both cases, arrays of tokens will be created, and a string variable called "Count" will be set to the number of tokens in the array. The '''pagetokens''' command returns (by default) all of the tokens on the page that contains the token passed as the parameter after the array name. You can filter the tokens that "pagetokens" includes in the array by appending an optional parameter describing the type of token you are looking for:<br />
<br />
<pre>--~Count|array;pagetokens;Everybondy;@{selected|token_id};npc</pre><br />
<br />
Will return only tokens on the page that represent characters that do not have a ''controlledby'' parameter set. The available options are "all" (default), "char", "graphic", "pc", and "npc".<br />
<br />
The '''selectedtokens''' command returns an array with all of the tokens that were selected when the script was called.<br />
<br />
You can also use an arbitrary string to create an array, specifying a delimiter with the '''fromstring''' command:<br />
<br />
<pre><br />
--&names|Fred<br />
--&names|+,Sally<br />
--&names|+,Ted<br />
--&names|+,Joyce<br />
--~|array;fromstring;,;[&names]<br />
</pre><br />
<br />
The above example builds a comma-separated string and then uses "fromstring" to create an array with 4 elements from it, specifying the comma as the delimiter.<br />
<br />
Finally, you can use the '''statusmarkers''' command to create an array with one entry for each active status marker on a specified token:<br />
<br />
<pre>--~|array;statusmarkers;Conditions;@{selected|token_id}</pre><br />
<br />
will create an array with one entry for each status active on the selected token. The array elements will be the internal name of the status (if you are using custom status marker packs, the names will be specified in the marker pack).<br />
<br />
'''Traversing Arrays'''<br />
<br />
Each array keeps track of an internal index position (starting at 0). Several commands let you manage this index:<br />
<br />
*'''getindex''' returns the current index value<br />
*'''setindex''' sets the index to the specified location in the array<br />
*'''getlength''' returns the number of elements in the array<br />
*'''indexof''' returns the index location of the specified element<br />
<br />
Other commands let you retrieve values from the array:<br />
<br />
*'''getfirst''' sets the index to 0 and returns the value at that position<br />
*'''getnext''' advances the index by 1 and returns the new current value<br />
*'''getprevious''' reduces the index by 1 and returns the new current value<br />
*'''getlast''' sets the index to the last elements in the array and returns the new current value<br />
<br />
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.<br />
<br />
'''Manipulating Array Elements'''<br />
<br />
Several array commands deal with inserting, removing, and modifying elements:<br />
<br />
*'''add''' works just like define, except that it takes an existing array and adds elements to it based on the passed parameters<br />
*'''remove''' looks for items matching each passed parameter and removes them from the indicated array if they exist<br />
*'''removeat''' allows you to specify an index location in the array and remove the element at that position<br />
*'''replace''' searches an array for a value and replaces all occurrences of it with a new value (if found)<br />
*'''sort''' sorts the elements in the array in ascending order<br />
*'''strinfigy''' returns a string variable that includes each array element separated by semicolons (;) <br />
<br />
'''Referencing Array Elements'''<br />
<br />
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.<br />
<br />
<pre><br />
!script {{<br />
--~dummy|array;pagetokens;myarray;@{selected|token_id}<br />
--~count|array;getcount;myarray<br />
--+Total:|There are [&count] graphical objects on the page<br />
--~testvar|array;getfirst;myarray<br />
--:loop|<br />
--+Value|[*[&testvar]:character_name]<br />
--~testvar|array;getnext;myarray<br />
--?[&testvar] -ne ArrayError|loop<br />
--+Loop1|Is Done!<br />
}}<br />
</pre><br />
<br />
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:<br />
<br />
<pre><br />
!script {{<br />
--~dummy|array;pagetokens;myarray;@{selected|token_id}<br />
--~count|array;getcount;myarray<br />
--+Total:|There are [&count] graphical objects on the page<br />
--%loopCounter|1;[&count]<br />
--+Value|[*[@myarray([&loopCounter])]:character_name]<br />
--%|<br />
--+Loop|Is Done!<br />
}}<br />
</pre><br />
<br />
This line : <nowiki>--+Value|[*[@myarray([&loopCounter])]:character_name]</nowiki> uses [@arrayName(index)] format (inside a [*characterid:attribute] syntax) to perform the same task as running through the loop with the index.<br />
<br />
(Note: Additional examples are on the way...)<br />
<br />
== For...Next Loops ==<br />
<br />
For...Next loops in ScriptCards are supported with the with the --% statement type. A loop is defined by starting off with:<br />
<br />
<pre><br />
--%LoopCounter|<start>;<end>;[step]<br />
</pre><br />
<br />
The start and end values are required, while the step parameter is optional. If the step is omitted, it will be assumed to be 1. A string variable named after the line tag ("LoopCounter" in the case above) will be created and will hold the current iteration value for the loop. Here is a real example:<br />
<br />
<pre><br />
--%LoopCounter|1;10;1<br />
</pre><br />
<br />
This will begin a loop identified by "LoopCounter" that will start at 1, increasing by 1 each iteration (the step) until it has completed 10 executions.<br />
<br />
The "next" statement is simply <code>--%|</code>, with no tag or parameters. This indicates to ScriptCards that it should increment the counter and go back to the beginning of the loop. Extending the example above:<br />
<br />
<pre><br />
!script {{<br />
--%LoopCounter|1;10;1<br />
--=Roll|1d20<br />
--+Loop|Counter is [&LoopCounter], roll was [$Roll]<br />
--%|<br />
}}<br />
</pre><br />
<br />
The <code>--%!|</code> sequence will break out of the loop, no matter how many iterations are remaining.<br />
<br />
The % and %! character sequences can also be used as part of a 1.2.1+ non-branching conditional to continue or break the loop:<br />
<br />
<pre><br />
--?"X[&RollInto]X" -eq "XX"|%<br />
</pre><br />
<br />
In this example, if the string variable RollInfo is empty, the loop will return to the top and continue with the next iteration, while:<br />
<br />
<pre><br />
--?"X[&RollInto]X" -eq "XX"|%!<br />
</pre><br />
<br />
Would cause the whole loop to end if the condition were true.<br />
<br />
== Referencing ==<br />
<br />
=== Roll Variables===<br />
<br />
Roll Variables can be referenced from the content portion of any line type, and from the tag portion of conditional statements. The referenced value is replaced when the line is executed.<br />
<br />
There are several modifiers that can be used to reference parts of a roll:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Modifier !! Meaning<br />
|-<br />
| No modifier || In a Direct Output Line (<nowiki>--+</nowiki>), GM Output Line (<nowiki>--*</nowiki>), or String Assignement (<nowiki>--&</nowiki>), 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<br />
|-<br />
| .Total || The end result of the roll equation. Formatting rules for "No Modifier" apply based on line type. <br />
|-<br />
| .Raw || The total value of the roll variable without any formatting, no matter what kind of line the reference is used in.<br />
|-<br />
| .Base || The cumulative result of any dice rolled in the Roll Text (Numeric modifiers are not included) <br />
|-<br />
| .Ones || The number of dice in the roll that came up as 1s <br />
|-<br />
| .Aces || The number of dice in the roll that came up as the maximum number on the die <br />
|-<br />
| .Odds || The number of dice in the roll that came up with an odd number <br />
|-<br />
| .Evens || The number of dice in the roll that came up with an even number <br />
|-<br />
| .RollText || The raw text of the roll that was use to generate the results <br />
|-<br />
| .Text || A text representation of the results of the roll, including the numbers rolled for each die <br />
|-<br />
| .tableEntryText || The text portion of the result of a table roll<br />
|-<br />
| .tableEntryImgURL || The image source portion of the result of a table roll<br />
|-<br />
| .tableEntryValue || If the tableEntryText is purely numeric, will contain the numeric value<br />
|}<br />
<br />
=== String Variables ===<br />
<br />
To reference a string variable, use the notation [&variablename]. String variables can be referenced in direct output, roll variable assignment, and string variable assignment statements.<br />
<br />
=== Character/Token Attributes ===<br />
<br />
A character or token attribute can be referenced from content portion of any type of line and is substituted when the line is executed. The general format for referencing a character attribute is [*ID:attribute]. ID can be a token ID or a character ID (these start with a dash). Additionally if you have specified a sourceToken or targetToken, you can substitute "S" or "T" for the ID (for example [*S:npc_type] will retrieve the npc_type attribute from the source token.<br />
<br />
By default, all attribute references will be pulled from the '''''character''''' object that the ID represents (either directly or by being a Token ID that represents a character).<br />
<br />
Keep in mind, that if you want to access the "max" of a character attribute (for example, the max hit points), then you cannot trust the name that your roll20 character sheet shows you when you hover your mouse over the max hit points. For example, this reference will not work: [*S:hp_max]. Instead, you need to use this reference: [*S:hp^].<br />
<br />
If your ID refers to a token, token attributes can be accessed by preceding the attribute name with "t-", for example [*S:t-aura1_radius]. Supported token attributes are:<br />
<br />
{|<br />
| t-name || t-id || t-statusmarkers || t-bar1_value<br />
|-<br />
| t-bar1_max || t-bar2_value || t-bar2_max || t-bar3_value<br />
|-<br />
| t-bar3_max || t-top || t-left || t-width<br />
|-<br />
| t-height || t-rotation || t-layer || t-aura1_radius<br />
|-<br />
| t-aura1_color || t-aura2_radius || t-aura2_color || t-aura1_square<br />
|-<br />
| t-aura2_square || t-tint_color || t-light_radius || t-light_dimradius<br />
|-<br />
| t-light_angle || t-light_losangle || t-light_multiplier || t-light_otherplayers<br />
|-<br />
| t-light_hassight || t-flipv || t-fliph || t-controlledby<br />
|-<br />
| t-_cardid || t-_pageid || t-imgsrc || t-bar1_link<br />
|-<br />
| t-bar2_link || t-bar3_link || t-represents || t-layer<br />
|-<br />
| t-isdrawing || t-name || t-gmnotes || t-showname<br />
|-<br />
| t-showplayers_name || t-showplayers_bar1 || t-showplayers_bar2 || t-showplayers_bar3<br />
|-<br />
| t-showplayers_aura1 || t-showplayers_aura2 || t-playersedit_name || t-playersedit_bar1<br />
|-<br />
| t-playersedit_bar2 || t-playersedit_bar3 || t-playersedit_aura1 || t-playersedit_aura2<br />
|-<br />
| t-lastmove || t-adv_fow_view_distance || t-has_bright_light_vision || t-has_night_vision<br />
|-<br />
| t-night_vision_distance || t-emits_bright_light || t-bright_light_distance || t-emits_low_light<br />
|-<br />
| t-low_light_distance || t-has_limit_field_of_vision || t-limit_field_of_vision_center || t-limit_field_of_vision_total<br />
|-<br />
| t-has_limit_field_of_night_vision || t-limit_field_of_night_vision_center || t-limit_field_of_night_vision_total || t-has_directional_bright_light<br />
|-<br />
| t-directional_bright_light_center || t-directional_bright_light_total || t-has_directional_dim_light || t-directional_dim_light_center<br />
|-<br />
| t-directional_dim_light_total || t-lightColor || || |<br />
|}<br />
<br />
'''''It is important to note that some attributes names on tokens have corresponding attribute names on characters, which represent different values. For example, [*T:id] returns the character ID, while [*T:t-id] returns the token ID.'''''<br />
<br />
=== Subroutine Parameters ===<br />
<br />
When using a gosub statement (-->) or a conditional marked as a gosub (prefixing the label with a > character), you can pass any number of parameters separated by semicolons (;) that the code in the subroutine can utilize.<br />
<br />
Subroutine parameters are numbered starting at 1, and are accessed by using the notation [%number%], so the first parameter is [%1%], the second is [%2%], etc.<br />
<br />
Parameter substitution happens on all line types, and happens prior to character attribute references or roll variable substitution.<br />
<br />
=== Campaign Attribute ===<br />
You can retrieve properties of the API's Campaign object with the [*C:attributename] syntax. For example, [*C:playerpageid] will retrieve the current player ribbon page from the Campaign object.<br />
<br />
=== Page Attributes ===<br />
If you have set the '''activepage''' parameter, you can retrieve page-related properties with the [*P:attributename] syntax, including the page's UDL parameters.<br />
<br />
=== Repeating Section Values ===<br />
<br />
You can reference repeating attribute data using the syntax [*R:attributename] syntax (similar to referencing standard character attributes). The currently active repeating row information will be used to retrieve attribute values. You can also retrieve the full attribute name for a repeating row attribute by using the [*R>attributename] notation. This is useful to pass to things like chatsetattr.<br />
<br />
=== Array Elements ===<br />
After an array has been declared, the elements can be referenced with [@arrayName(index)]. Array indices start at 0.<br />
<br />
== Deferred Resolution for Meta Scripts ==<br />
<br />
As of 1.2.9, ScriptCards supports a deferral character for use when calling another API script with via the --@ statement, to defer processing of meta script references so they get processed prior to the sub-API call insted of prior to ScriptCards execution. To defer this processing for meta script (SelectManager, Fetch) by inserting a deferral character into the meta call. For example, if I want to have ScriptCards call TokenMod as if the token for "Quej Gr'stra" (yes, I let Roll20 name my test NPCs) I could use something like this:<br />
<br />
--@token-mod|{^& select Quej Gr'stra} _on showname<br />
<br />
The "^" in between { and & will prevent SelectManager from seeing the call when the ScriptCard script is processed, but the --@ statement will remove the deferral character so the command that will be sent by ScriptCards is:<br />
<br />
!token-mod {& select Quej Gr'stra} --on showname<br />
<br />
With the deferral character removed, SelectManager will see the {& select ...} and do its magic.<br />
<br />
While the default deferral character is "^", the deferral character is a setting that can be changed:<br />
<br />
--#deferralcharacter|%<br />
<br />
Will make % the deferral character for future --@ statements in the running script.<br />
<br />
There are currently three supported Meta script structures: {^&...} for SelectManager, @^(...) and *^(...) for fetch, where the ^ in the structures here represents the placement of the deferral character.<br />
<br />
== Arrays ==<br />
<br />
Arrays are a new data type introduced in version 1.1.12 of ScriptCards, and are manipulated with associated function (--~) commands.<br />
<br />
* Arrays are a lists of strings. Items in an array cannot contain the semi-colon (;) character, as that is used to separate parameters in the function code that deals with arrays.<br />
* Arrays are accessed via the --~ script command. In some cases, the value of the tag (variable name) for array commands is not used, and can be a dummy value or simply omitted. I have omitted them in the statements below.<br />
* All commands that DO return a value return string values, even if the content is numeric.<br />
* If a command returns a value and there is some sort of reason that it isn't an array value, you will get "ArrayError" in the return value. This can happen if you reach the end of an array while stepping through it, for example, so checking for "ArrayError" can serve as the end condition for a loop.<br />
* Each array keeps track of its current index, allowing you to step forward and backwards through arrays.<br />
* Any number of arrays can be defined.<br />
* Unlike string variables and roll variables, array variables cannot (currently) be referenced directly. It is necessary to use the function (--~) syntax to manipulate arrays and get values from them as strings for use in other parts of your script.<br />
<br />
<br />
== Reentrant Scripts ==<br />
<br />
Reentrant scripts allow you to create buttons in your script code that will re-execute the script at a given label within the code. If you set the reentrant setting (--#reentrant|somevalue) to a non-zero value, your setting and variable information will be preserved between executions. Reentrant script can be used to present menus or choices and then continue acting.<br />
<br />
Reentrant buttons are created with the [rbutton]Caption::ReentryLabel;Parameter[/rbutton] construct. The caption will be displayed on the generated button. ReentryLabel is the name of a label in your script that the button will jump to when clicked, and Parameter will be passed in as a string value called "reentryval".<br />
<br />
Example:<br />
<pre><br />
!script {{<br />
--#reentrant|testing<br />
--=Roll|1d20<br />
--+Roll|[$Roll]<br />
--&String|That was a [$Roll.Raw]!<br />
--~x|array;define;MyArray;Apple;Banana;Orange<br />
--+Try it|[rbutton]Hello!::EXEC_PC_SPELL;9[/rbutton]<br />
--X|<br />
<br />
--:EXEC_PC_SPELL|<br />
--+ReentryVal|[&reentryval]<br />
--+The value of Roll is|[$Roll]<br />
--+Value of String|[&String]<br />
--+Array|[@MyArray(0)]<br />
--X|<br />
}}<br />
</pre><br />
<br />
This script sets up some variables and then displays a button labeled "Hello!". If the user clicks the button, the script will be re-entered starting at the "EXEC_PC_SPELL", which will display the content of the variables from the original execution.<br />
<br />
'''''Note: This section needs to be expanded upon'''''<br />
<br />
== Procedure Libraries ==<br />
<br />
You can now create handouts in your game in Roll 20 with the name format "ScriptCards Library NAME", where name is a name you assign to the library. Library names are case sensitive. It is my hope that the more proficient ScriptCards scripters out there will provide procedure libraries (or procedures that can be included in libraries) for others to use to make their scripting life easier. Be they specific to a game system, or to a type of activity, I think a robust set of libraries that GMs could use to enhance their scripting capabilities would be very valuable to the community. Should such things begin to emerge, I’ll create a portion of the ScriptCards Wiki page to house them.<br />
<br />
To include one or more libraries in a script, use the +++libname+++ directive (does not need a -- line associated with it). Multiple library names can be specified by separating them with semicolons (i.e., +++General;dnd5elib;Colorize+++ would include three libraries (General, dnd5elib, and Colorize).<br />
<br />
Included libraries are separated from the main script code by the automatic inclusion of "--X|" before the first library is appended to the script, and all libraries are loaded at the end of the script before script processing takes place.<br />
<br />
Procedures and labels in libraries can be used just as if they were included in the body of your script. Note that this DOES mean that you could, technically, jump into a library with a direct branch (--^) or direct branch conditional, but I recommend using libraries to store reusable procedures.<br />
The Notes section of the library handout stores the library code, and is written just like any other ScriptCards code except:<br />
<br />
* They cannot use roll queries (?{Some Prompt:}) to get information from the user at execution time.<br />
* They cannot use @{} notation to access character and token information.<br />
<br />
Both of these limitation stem from the fact that Procedure Libraries are not processed by the chat server, which is what handles these items.<br />
<br />
Here is an example of handling damage modifications (resistance, vulnerability, and immunity) in D&D 5E with a library:<br />
<br />
<pre><br />
!script {{<br />
+++dnd5elib+++<br />
--#|Damage Modifiers Test<br />
--#targettoken|@{target|token_id}<br />
-->Lib5E_CheckDamageModifiers|ResistType;fire<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] fire damage<br />
<br />
-->Lib5E_CheckDamageModifiers|ResistType;cold<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] cold damage<br />
<br />
-->Lib5E_CheckDamageModifiers|ResistType;poison<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] poison damage<br />
<br />
-->Lib5E_CheckDamageModifiers|ResistType;acid<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] acid damage<br />
<br />
--X|<br />
}}<br />
</pre><br />
<br />
Library content (In a handout called “ScriptCards Library dnd5elib” NOTE: Paste into Notepad first and then paste into the handout in Roll20 to avoid bringing over HTML formatting from the web site):<br />
<br />
<pre><br />
--/|ScriptCards Library: dnd5elib version 0.0.1<br />
--/|Provides various utility procedures for D&D 5E games<br />
<br />
--/|Lib5E_CheckDamageModifiers handle damage resistance, vulnerability, and immunity. <br />
--/|Pass a string variable to be filled with a string to be appended to a dice roll and the damage type <br />
<br />
--:Lib5E_CheckDamageModifiers|damageVariableName;damageType<br />
--&[%1%]|<br />
--?"[*T:npc_vulnerabilities]" -inc "[%2%]"|>_Lib5E_IsVulnerable;[%1%]<br />
--?"[*T:npc_resistances]" -inc "[%2%]"|>_Lib5E_IsResistant;[%1%]<br />
--?"[*T:npc_immunities]" -inc "[%2%]"|>_Lib5E_IsImmune;[%1%]<br />
--<|<br />
<br />
--:_Lib5E_IsVulnerable| --&[%1%]| * 2 [Vulnerable] --<|<br />
--:_Lib5E_IsResistant| --&[%1%]| \ 2 [Resistant] --<|<br />
--:_Lib5E_IsImmune| --&[%1%]| * 0 [Immune] --<|<br />
</pre><br />
<br />
The idea is that the functions in the library create a string that can be appended to a roll to modify the output based on resistances, so you pass Lib5E_CheckDamageModifiers the name of the string variable you want to use and the damage type. The variable (ResistType in this case) will include either nothing, “* 2 [Vulnerable]”, “\ 2 [Resistant]”, or “* 0 [Immune]” which can be included in a roll assignment (--=) to modify the damage as appropriate. The order here might be important if an NPC is misconfigured to be both resistant and immune to the same damage type. Since immune is an absolute, having it last ensures that it will override resistant or vulnerable. A creature that is both vulnerable and resistant (again, misconfigured) will come back as resistant since that condition is checked after vulnerable.<br />
Some notes: I prefix my library labels with either “Lib5E_” or “_Lib5E_” as a clarity convention. This isn’t strictly necessary but you should be aware that if two libraries (or if your script and a library) define the same label, the last label defined will win. Since libraries are appended to the end of the script in the order you include them in the +++libname+++ directive, you can somewhat control this, but it is probably best to avoid re-declaring labels. <br />
<br />
In my case, items beginning with “Lib5E_” are intended to be called by scripts, while items beginning with “_Lib5E_” are intended to be used as subroutines by the “public” procedures. Of course, there is no reason you couldn’t call them directly.<br />
<br />
You might also note that I’ve included some library information in comment lines (--/|) at the top of the library. These are ignored by ScriptCards, and are a good way to convey requirements, parameters, usage information, etc.<br />
<br />
== Example Libraries ==<br />
<br />
=== dnd5elib ===<br />
<br />
[https://github.com/kjaegers/ScriptCards Download the dnd5elib Library from the ScriptCards GitHub]<br />
<br />
The '''dnd5elib''' library provides a collection of utility procedures that help simplify dealing with the D&D 5E Official Sheet. Some of the procedures in this library require '''chatsetattr''' to be installed in your game. This is a growing library, and currently only has a handful of routines. They are:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Procedure Name !! Notes<br />
|-<br />
| style="white-space:nowrap" | Lib5E_CheckDamageModifiers || This procedure can be used to evaluate vulnerabilities, resistances, and invulnerabilities on an NPC. After setting the --#target| parameters, pass the Lib5E_CheckDamageModifiers procedure a variable name (no reference information) and a damage type (i.e., fire, cold, bludgeoning, etc.) and a string variable with the name passed in as the first parameter will be created that contains text that can be included in a roll line (--=) in order to modify the roll as appropriate. For example, '''-->Lib5E_CheckDamageModifiers|ResistType;fire''' will check the current target character's attributes for "fire" and will either return an empty string (no references), "* 0 [Immune]" if the creature is immune, "\ 2 [Resistant]" if the creature is resistant, or "* 2 [Vulnerable]" if the creature is vulnerable to fire damage.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_DeductSpellSlot || Pass in a character_id and a slot level, and the script will expend one spell slot of that level, capping the value at 0 slots remaining. For Example '''<nowiki>-->Lib5E_DeductSpellSlot|@{selected|character_id};1</nowiki>''' to deduct a first level spell slot from the selected character.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_FindResource || Used to locate a resource value on a character. Pass in a character_id, a resource name, and two variable names. The procedure will check both repeating and non-repeating resources looking for a resource whose name matches what was passed in and return three variables. The first will be a string variable named for the 3rd parameter and contains the attribute name of the resource's "name" field. The second will be a string variable named after parameter 4 and contains the resource's value field attribute name, and the third variable is a Roll Variable, also named after the 4th parameter that contains the current resource value. Example: '''<nowiki>-->Lib5E_FindResource|@{selected|character_id};Crossbow bolts;ResName;ResValue</nowiki>''' will find "Crossbow bolts" as a resource on the character and return [&ResName] which is the name of the resource attribute, [&ResValue] which is the '''name of the attribute that stores the value''' and [$ResValue] which is the current numeric value of the resource.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Global_Attack_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Attack Modifiers (repeating_tohitmod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Bless" for 1d4 active and "Being Cool" for +2 active, I will get a return string " + 1d4 [Bless] + 2 [Being Cool]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Save_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Save Modifiers (repeating_savemod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Bless" for 1d4 active and "Being Cool" for +2 active, I will get a return string " + 1d4 [Bless] + 2 [Being Cool]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Skill_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Skill Modifiers (repeating_skillmod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Guidance" for 1d4 active and "Being Cool" for +2 active, I will get a return string " + 1d4 [Guidance] + 2 [Being Cool]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_AC_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Save Modifiers (repeating_savemod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Shield of Faith" with a value of 2 active, I will get a return string " + 2 [Shield of Faith]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Damage_Modifiers || Pass a character ID and TWO string variable to set the return value. The first string will be for normal damage, and the second will be the additional damage on a crit. This procedure will look through the Global Damage Modifiers (repeating_damagemod_*) for rows that are active (checked on the character sheet) and return two strings with the dice rolls and descriptions for them (for example, if I have "Sneak Attack" with a value of 1d6 normal and 1d6 critical damage active, I will get a return string " + 1d6 [Sneak Attack]" and another string of " + 1d6 [Sneak Attack CRIT]" that can be used in a dice rolls.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_DivineSmiteDice || Used to calculate the number of dice to be rolled for a paladin's Divine Smite. Pass a target token id, a spell slot level, and a string variable to be set to the dice roll amount based on the NPC_TYPE attribute of the target token. The returned variable will contain a dice roll (like "3d8" that can be used in a --= line)<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Character_Summary || Pass a character ID to outputs a mini character sheet, including clickable buttons for attacks, actions, legendary actions, etc. Will automatically detect a PC vs NPC and output the appropriate sections.<br />
|}<br />
<br />
Due to formatting issues with the Wiki, the library code has been moved to a [https://gist.github.com/kjaegers/52f6049ddd257f0a1288aca4bbde13c5 GITHUB GIT]. Please view the GIST in raw mode and copy the text and paste it into a handout called "ScriptCards Library dnd5elib" in your Roll20 Game.<br />
<br />
== What to Know if you are Coming from PowerCards ==<br />
<br />
''Note: This section is a work in progress.''<br />
<br />
While ScriptCards and PowerCard have very similar output goals, their internals and use are quite different. The table below summarizes some of the major differences between the scripts.<br />
<br />
::{| class="wikitable"<br />
|-<br />
! PowerCards !! ScriptCards <br />
|-<br />
| With a handful of exceptions, all lines in a PowerCard macro are intended to produce a line of output on the final card. || With ScriptCards, ONLY the <code>--+</code> and <code>--*</code> statement types produces output <br />
|-<br />
| PowerCards lines begin with two dashes (<code>--</code>) followed by a unique tag name for the line, followed by a vertical bar and the content for the line. || ScriptCards lines begin with two dashes (<code>--</code>) followed by a '''statement type identifier''', which is a single character that identifies the type of line to the interpreter. This is followed by a tag (frequently optional), a vertical bar, and the parameters for the statement being executed.<br />
|-<br />
| PowerCard macros are always processed top to bottom. Lines can be hidden so they don't output anything, but there is no looping or branching (--SkipTo looks like a branch, but it just hides all of the lines until the referenced label. || ScriptCards scripts support true branching, including direct branching (<code>--^</code>) and procedure branching (<code>--></code>) and (<code>--<</code>). Procedures support parameters and a call stack so procedures can be nested to call other procedures.<br />
|-<br />
| All lines in a PowerCards macro need to have unique tags because PowerCards builds the card as a single JavaScript object using the tag names to store what will be displayed. This is why repeated tag names always result in the last one being shown. || ScriptCards tags do not need to be unique, and in the case of many line types are optional.<br />
|-<br />
| PowerCards conditionals result in either showing or hiding the line they are on. || ScriptCards conditionals '''''only''''' support branching as the result of the comparison. This branching can be direct (a GOTO) or procedural (a GOSUB) '''''NOTE: As of version 1.2.0, ScriptCards also supports roll/string variable assignment as a result of conditional evaluation'''''<br />
|-<br />
| PowerCards relies on the Roll20 [[Quantum Roll]] server and inline rolls for all dice functions || ScriptCards includes its own dice roll parser, and '''''does not support''''' inline rolls.<br />
|-<br />
| PowerCards RollIDs (often mistaken for variables) are assigned by analyzing the results of an inline roll, and cannot be referenced in other rolls, so you can't roll a <code>1d4</code> and then roll a <code>1d20</code> and add the <code>1d4</code> result because all of the rolls happen on the chat server before PowerCards gets the macro text. || ScriptCards supports two types of variables: Roll Variables and String Variables. Because ScriptCards uses its own roll parser and is not dependent upon the chat server, rolls and their results can be used in other rolls, math functions, output, etc.<br />
|}<br />
<br />
== Example Scripts ==<br />
<br />
Below are some sample scripts that utilize the various statement types in ScriptCards:<br />
<br />
=== Divine Smite ===<br />
<br />
This script will prompt the user for a spell slot level to expend on a divine smite. It will check the target's npc_type to see if it is an Undead or Fiend, which adds an additional d8 to the smite roll.<br />
<br />
[[File:ScriptCards Divine Smite.png|Divine Smite Script Output]]<br />
<br />
<pre><br />
!scriptcard {{<br />
--#title|Divine Smite<br />
--=DiceCount|?{Spell Slot Level?|1|2|3|4|5|6|7|8|9} + 1<br />
--=IsFiendOrUndead|0<br />
--?"@{target|npc_type}" -inc fiend|>IsBoosted<br />
--?"@{target|npc_type}" -inc undead|>IsBoosted<br />
--=TotalDice|[$DiceCount] + [$IsFiendOrUndead]<br />
--=SmiteRoll|[$TotalDice]d8<br />
--#emoteText|@{selected|token_name} smites @{target|token_name}<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
--+Smite|deals [$SmiteRoll] radiant damage.<br />
--X|<br />
<br />
--:IsBoosted|<br />
--=IsFiendOrUndead|1<br />
--<|<br />
}}<br />
</pre><br />
<br />
==== How It Works ====<br />
<br />
The first line sets the "title" card parameter to "Divine Smite".<br />
<br />
Line 2 Shows a query to the user asking for the spell slot level, adds one and stores the value in the "DiceCount" Roll Variable. The query/dropdown is generated by the chat server prior to the script being executed.<br />
<br />
Line 3 defaults the "IsFiendOrUndead" Roll Variable to 0.<br />
<br />
Lines 4 and 5 compare the target's "npc_type" attribute (passed by the chat server as text) to see if they include either "undead" or "fiend". If true, the IsBoosted subroutine will be called. No parameters are passed to this subroutine.<br />
<br />
Line 6 sets the "TotalDice" variable to the base (DiceCount) number plus the IsFiendOrUndead number, which will be a 0 or a 1.<br />
<br />
Line 7 calculates "SmiteRoll" by rolling a number of d8 equal to the "TotalDice" value.<br />
<br />
Lines 8-10 set the parameters for the emote, which appears above the card content. By setting the sourceToken and the targetToken, their icons will appear in the emote surrounding the text describing the action.<br />
<br />
Line 11 is the only line that actually produces output on the card. It results in "Smite deals # radiant damage".<br />
<br />
Line 12 ends the script execution, preventing the script from continuing and running the subroutines out of context.<br />
<br />
Lines 14-16 are the IsBoosted subroutine, starting with the :IsBoosted label. The IsFiendOrUndead variable is set to 1, and a return from subroutine is executed.<br />
<br />
=== Magic Missile ===<br />
<br />
This script demonstrates using a loop and calling a subroutine to fire a number of missiles determine by the spell slot level used to cast the spell.<br />
<br />
[[File:ScriptCards_MagicMissile_Fixed.png|Magic Missile Script Output]]<br />
<br />
<pre><br />
!scriptcard {{ <br />
--#title|Magic Missile<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
--=MissileCount|?{Spell Slot Level?|1|2|3|4|5|6|7|8|9} + 2<br />
--=DisplayCount|1<br />
--=MissileDamage|0<br />
--#leftsub|Slot level ?{Spell Slot Level?}<br />
--#rightsub|Ranged Attack<br />
--#emoteText|Fred uses a level ?{Spell Slot Level?} spell slot to fire [$MissileCount.Total] missiles of magical force!<br />
--:MissileLoop|<br />
-->FireMissile|<br />
--=DisplayCount|[$DisplayCount] + 1<br />
--?[$DisplayCount] -le [$MissileCount]|MissileLoop<br />
--+Total|Total damage is [$MissileDamage]<br />
--X|<br />
<br />
--:FireMissile|<br />
--=ThisMissile|1d4 + 1<br />
--=MissileDamage|[$MissileDamage] + [$ThisMissile]<br />
--+Missile|[$DisplayCount.Total] Hits for [$ThisMissile] [b]force[/b] damage<br />
--<|<br />
}}<br />
</pre><br />
<br />
==== How It Works ====<br />
<br />
Lines 1-3 set the card title, the source token and the target token. Setting these tokens causes their icons/avatars to appear in the Emote section of the card.<br />
<br />
Line 4 asks the user what spell slot level they wish to use to cast magic missile. The number of missiles fired is equal to 2 plus the spell level, and this is stored in the MissileCount variable.<br />
<br />
Line 5 stores a 1 in the DisplayCount variable. This will be used to control the loop to determine the number of missiles fired and the missile number when displaying damage rolls.<br />
<br />
Line 6 initializes MissileDamage to 0<br />
<br />
Line 7 sets the left subtitle to the text "Slot Level #", where # is the spell slot level being used.<br />
<br />
Line 8 sets the right subtitle to the text "Ranged Attack".<br />
<br />
Line 9 sets the emoteText parameter with a description of the action, including the slot level and number of missiles fired.<br />
<br />
Line 10 is a label for the missile firing loop<br />
<br />
Line 11 Calls the "FireMissile" subroutine<br />
<br />
Line 12 increases the DisplayCount variable by 1<br />
<br />
Line 13 Checks to see if there are still missles to fire (DisplayCount <= MissileCount) and if so branches to MissileLoop<br />
<br />
Line 14 Displays the total damage dealt by the spell.<br />
<br />
Line 15 stops execution of the script to prevent out of context execution of the subroutine.<br />
<br />
Lines 76-21 are the FireMissile subroutine, beginning with the FireMissile label. The 1d4+1 is rolled and assigned to "ThisMissile". The result is added to the existing MissileDamage total, and a line for the current missile is displayed with the missile number and the damage for the missile.<br />
<br />
=== Longsword Attack ===<br />
<br />
This script demonstrates a standard 5E D&D melee weapon attack, including detection of misses, fumbles, hits, and critical hits. If installed, alterbars is used to decrement the target's BAR3 value by the damage dealt.<br />
<br />
[[File:ScriptCards Longsword.png|Longsword Script Output]]<br />
<br />
<pre><br />
!scriptcard {{<br />
--#title|Longsword<br />
--#leftsub|Melee Attack<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
--#emoteText|@{selected|token_name} attacks @{target|token_name}<br />
--=TargetAC|@{target|npc_ac}<br />
--?[$TargetAC.Total] -gt 0|DoneWithAC<br />
--=TargetAC|@{target|ac}<br />
--:DoneWithAC|<br />
--=AttackRoll|1d20 + @{selected|strength_mod} [STR] + @{selected|pb} [PROF]<br />
--+Attack|@{selected|token_name} rolls [$AttackRoll] vs AC [$TargetAC].<br />
--?[$AttackRoll.Base] -eq 20|Crit<br />
--?[$AttackRoll.Base] -eq 1|Fumble<br />
--?[$AttackRoll.Total] -ge [$TargetAC.Total]|Hit<br />
--+Miss|The attack missed.<br />
--^Final|<br />
<br />
--:Fumble|<br />
--+Fumble!|The attack went horribly wrong.<br />
--^Final|<br />
<br />
--:Hit|<br />
--=Damage|1d8 + @{selected|strength_mod} [STR]<br />
--+Hit!|The attack hit @{target|token_name} for [$Damage] slashing damage.<br />
--@alter|_target|@{target|token_id} _bar|3 _amount|-[$Damage]<br />
--^Final|<br />
<br />
--:Crit|<br />
--=Damage|1d8 + @{selected|strength_mod} [STR] + 1d8 [CRIT]<br />
--+Critical Hit!|The attack hit @{target|token_name} for [$Damage] slashing damage.<br />
--@alter|_target|@{target|token_id} _bar|3 _amount|-[$Damage]<br />
<br />
--:Final|<br />
}}<br />
</pre><br />
<br />
==== How it Works ====<br />
<br />
In lines 1-5, we set the title, subtitle, and emote text along with the tokens for the emote area.<br />
<br />
Lines 6-9 allow us to determine the AC of the target. On the 5E Roll20 sheet, NPCs armor class is stored in "npc_ac", while PCs armor class is in "ac". First we grab npc_ac and if it is zero, we check AC.<br />
<br />
Line 10 rolls the attack roll, rolling 1d20 and adding the attacker's strength modifier and proficiency bonus<br />
<br />
Line 11 displays the result of the attack roll on the card<br />
<br />
Lines 12-14 determine what kind of result the attack had. If the .Base value of the roll was 20, we branch to "Crit". If it was 1, we branch to "Fumble". If the .Total value of the roll was greater than or equal to the AC that was determined in Lines 6-9, we branch to Hit.<br />
<br />
Assuming we didn't branc anywhere, the result of the attack was a miss, so we display that on line 15 and then branch to "Final"<br />
<br />
This is followed by three branch segments, :Fumble, :Hit, and :Crit. A fumble displays a text message and branches to :Final.<br />
<br />
On a hit or a crit, we roll Damage (adding additional damage dice on a crit). We display a "Hit!" or "Critical Hit!" message and then make an API call to AlterBars, passing it the token id, bar we want to modify (3 in this case), and the amount we want to modify by the Damage value.<br />
<br />
=== Party Health Status ===<br />
<br />
This example calculates the current Hit Points remaining and HP percentage for each character and creates a color-coded display with the current party status.<br />
<br />
[[File:ScriptCards Party Health.png]]<br />
<br />
<pre><br />
!scriptcard {{<br />
--#title|Party Status<br />
--#titleCardBackground|#33CC33<br />
--#oddrowbackground|#bfee90<br />
--#evenrowbackground|#90eebf<br />
-->HealthCheck|@{Quej Grastra|character_id}<br />
-->HealthCheck|@{Brim Cheuto|character_id}<br />
-->HealthCheck|@{Odug Ututees|character_id}<br />
--X|End of card Execution<br />
<br />
--:HealthCheck|<br />
--=HealthPerc|[*[%1%]:hp] / [*[%1%]:hp^] * 100 \ 1<br />
--=HealthColor|000000<br />
--?[$HealthPerc.Total] -gt 50|HealthSkip<br />
--=HealthColor|FF0000<br />
--:HealthSkip|<br />
--+[*[%1%]:character_name]|has [#[$HealthColor.RollText]][*[%1%]:hp] of [*[%1%]:hp^][/#] HP [R]([$HealthPerc.Total]%)[/R]<br />
--<|End of HealthCheck<br />
}}<br />
</pre><br />
<br />
==== How it Works ====<br />
<br />
Lines 1-4, we set the card title, and set the title background and row background colors to shades of green.<br />
<br />
Lines 5-7 make gosub calls the the "HealthCheck" subroutine, passing in the character ID of each of the named characters (these are the names of the characters in my test game)<br />
<br />
Line 8 terminates the script execution.<br />
<br />
The remaining lines of the script are the HealthCheck subroutine, which works like this:<br />
<br />
Line 10 is the subroutine label (:HealthCheck)<br />
<br />
Line 11 uses the character id passed as a parameter and combines it with character attribute lookup *(...) to retrieve the value of "hp" and "hp<nowiki>^</nowiki>" for the character. The <nowiki>^</nowiki> character is used to specify that we want the MAX value for this attribute for the second call. We divide these two numbers and multiple by 100 to get a percentage. Finally, we use integer division by 1 to round the percentage and drop the decimals. The end result gets stored in the HealthPerc roll variable.<br />
<br />
Line 12 defaults to color of the health text to black<br />
<br />
Line 13 check to see if the health percentage is greater than 50. If so, it branches to HealthSkip, preventing the script from executing line 13.<br />
<br />
Line 14 sets the color of the health text to red<br />
<br />
Line 15 is the label that will be branched to from Line 13 to skip the red coloring<br />
<br />
Line 16 again uses character attribute substitution and the passed parameter value to output a display line containing the character name, the colorized health total, and the percentage value. The percentage is right-justified.<br />
<br />
Line 17 returns from the HealthCheck subroutine.<br />
<br />
=== Expanded Magic Missile Script ===<br />
<br />
This is the expanded and enhanced version of the Magic Missile script covered in {{yt|watch?v=u50xvNzS9Zk | this video}}. It includes visual and audio effects, checking and deducting spell slots, and applying damage using either Token-Mod or Alterbars.<br />
<br />
<pre><br />
!scriptcard {{ <br />
--#title|Magic Missile<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
<br />
-->GetAndCheckSlotInformation|<br />
<br />
--=MissileCount|[$SlotLevel] + 2<br />
--=DisplayCount|1<br />
--=MissileDamage|0<br />
--#leftsub|Slot level [$SlotLevel]<br />
--#rightsub|Ranged Attack<br />
--#emoteText|@{selected|character_name} uses a level [$SlotLevel.Total] spell slot to fire [$MissileCount.Total] missiles of magical force!<br />
<br />
--:MissileLoop|<br />
-->FireMissile|<br />
--=DisplayCount|[$DisplayCount] + 1<br />
--?[$DisplayCount] -le [$MissileCount]|MissileLoop<br />
--+Total|Total damage is [$MissileDamage]<br />
-->DeductSpellSlot|<br />
--#rightsub|Level [$SlotLevel] Left: [$SlotsRemaining] <br />
-->PlayEffects|none;burst-smoke;beam-magic;spell_01<br />
-->ApplyDamageTokenmod|@{target|token_id};3;-[$MissileDamage]<br />
-->ApplyDamageAlterbars|@{target|token_id};3;-[$MissileDamage]<br />
--X|<br />
<br />
--:FireMissile|<br />
--=ThisMissile|1d4 + 1<br />
--=MissileDamage|[$MissileDamage] + [$ThisMissile]<br />
--+Missile|[$DisplayCount.Total] Hits for [$ThisMissile] [b]force[/b] damage<br />
--<|<br />
<br />
--:GetAndCheckSlotInformation|<br />
--=SlotLevel|?{Spell Slot Level?|1|2|3|4|5|6|7|8|9}<br />
--=SlotsTotal|[*S:lvl[$SlotLevel]_slots_total]<br />
--=SlotsExpended|[*S:lvl[$SlotLevel]_slots_expended]<br />
--?[$SlotsExpended.Total] -ge [$SlotsTotal.Total]|NoSlotsLeft<br />
--<|<br />
<br />
--:NoSlotsLeft|<br />
--+|[*S:character_name] has no level [$SlotLevel.Total] spell slots available.<br />
--X|<br />
<br />
--:DeductSpellSlot|<br />
--=SlotsExpended|[$SlotsExpended] + 1<br />
--@setattr|_charid [*S:character_id] _lvl[$SlotLevel]_slots_expended|[$SlotsExpended] _silent<br />
--=SlotsRemaining|[$SlotsTotal] - [$SlotsExpended]<br />
--<|<br />
<br />
--:PlayEffects|Parameters are : source effect; target effect; line effect; sound effect<br />
--vtoken|@{selected|token_id} [%1%]<br />
--vtoken|@{target|token_id} [%2%]<br />
--vbetweentokens|@{selected|token_id} @{target|token_id} [%3%]<br />
--@roll20AM|_audio,play,nomenu|[%4%]<br />
--<|<br />
<br />
--:ApplyDamageTokenmod|Parameters are tokenid;bar#;amount<br />
--@token-mod|_ignore-selected _ids [%1%] _set bar[%2%]_value|[%3%]<br />
--<|<br />
<br />
--:ApplyDamageAlterbars|<br />
--@alter|_target|[%1%] _bar|[%2%] _amount|[%3%]<br />
--<|<br />
}}<br />
</pre><br />
<br />
[[Category:Featured articles]]</div>5004103https://wiki.roll20.net/Script:ScriptCardsScript:ScriptCards2021-09-29T05:37:57Z<p>5004103: /* dnd5elib */</p>
<hr />
<div>{{revdate}}<br />
== Introduction ==<br />
'''ScriptCards''' provides a script interpreter that can be used to create powerful macros that display the results of player/NPC actions, or display other information in a pleasing visual format in your game's chat window. The scripting language contains variables (both dice-roll (enhanced numerics) and strings) as well, conditionals, branching, subroutines with parameters, and a set of built-in functions to simplify working with Roll20 information.<br />
{{script overview<br />
|name=ScriptCards<br />
|author={{user profile|2365448|Kurt J.}}<br />
|code=<br />
|version=1.4.0e<br />
|lastmodified=2021-09-24}}<br />
ScriptCards is not game-system specific, and can be used with any system/sheet. Near the end of this Wiki there is a section set aside for libraries that can implement system-specific tasks, with the hope that enthusiasts playing particular systems will create and share utility functions that can be utilized by the wider community.<br />
<br />
The default display style for ScriptCards output is similar to the format used to document player and NPC abilities in Dungeons and Dragons 4th Edition, but does not have any system ties to D&D4E.<br />
<br />
Current OneClick Version : 1.4.0e<br />
<br />
Current Development Version : 1.4.4<br />
<br />
'''''<big>Critically Important: ScriptCards does not use/parse inline rolls. ScriptCards includes its own built-in dice roll parser to allow for the use of variables inside dice rolls. As of version 1.2.3, ScriptCards will now take inline rolls and substitute the total result value in statement strings, meaning that you can utilize inline rolls but ScriptCards will only see the result of the roll, and not parse the roll components itself.</big>'''''<br />
<br />
* {{fpl|9752053/ ScriptCards thread}}<br />
** {{fpl|10000297/ Scritpcard API Working and Sharing}}<br />
* https://github.com/kjaegers/ScriptCards/tree/main/ScriptCards_API - GitHub repository for source before the one-click version is updated.<br />
* {{yt.be|hyR7Jnq4mQM ScriptCards Intro}} 45min, Jan 2021<br />
* {{yt.be|u50xvNzS9Zk ScriptCards Magic Missile Deep Dive}} 39min, Feb 2021<br />
<br />
<br />
__TOC__<br />
=== Is ScriptCards Related to [[PowerCards]]? ===<br />
<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
Check the '''[[#What to Know if you are Coming from PowerCards|What to Know if you are Coming from PowerCards]]'''-section for a comparison table between the two scripts.<br />
<br />
== What is a ScriptCard Script ==<br />
<br />
A ScriptCard Script is text written into the chat window (either typed directly, pasted, or run via a macro) that will produce a card of information in the [[text Chat|chat window]]. A ScriptCard Script is composed of an [[API]] command: <code><nowiki>!scriptcard {{ }}</nowiki></code> enclosing any number of lines that determine the output that will be added to the card. At it simplest, the following macro:<br />
<br />
<pre>!scriptcard {{ }}</pre><br />
<br />
Will produce just a title card that displays “ScriptCards” as the name:<br />
<br />
[[File:Scriptcard blank.png]]<br />
<br />
Of course, this is just the simplest type of macro and isn’t very useful. In order to produce useful output, we need to include lines between the <code><nowiki>{{</nowiki></code> and <code><nowiki>}}</nowiki></code> that direct the API script as to what it should do.<br />
<br />
== Structure of a ScriptCard Line ==<br />
<br />
All ScriptCard lines begin with two dashes, followed by an ''statement identifier character'' that lets ScriptCards what type of line it is. There are several of these, and they are detailed in the next section. After the line type identifier, a Tag name 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.<br />
<br />
Following the Tag is a vertical bar, and then the content of the line itself. Again, each type of line might interpret this content differently.<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Identifier !! Statement Type !! Tag !! Content !! Notes<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--/</nowiki> || Comment || unused || unused || The <code>--/</code> 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--#</nowiki> || 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").<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--+</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--=</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--&</nowiki> || Assign String 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. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--@</nowiki> || 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 (i.e., [[TokenMod|!token-mod]], or [[ChatSetAttr|!setattr]], etc.)<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--:</nowiki> || 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<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--^</nowiki> || Branch To || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--></nowiki> || Call Procedure || 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<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--<</nowiki> || 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.<br />
|- <br />
| style="white-space:nowrap" | <nowiki>--?</nowiki> || Conditional Branch || Condition to be evaluated || True Branch Label<nowiki>|</nowiki>False Branch Label || The condition will be evaluated and execution will jump to one of the two indicated branches (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 included a semicolon separated list of parameters. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--s</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--l</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--v</nowiki> || 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+'''''<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--e</nowiki> || Echo to Chat || Name to send chat command as || Chat message to send || Variable substitution takes place on the tag and content.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--R</nowiki> || Retrieve Repeating Section Row information || "find", "first", or "next" || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--~</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--c</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--i</nowiki> || Information Request || User Prompt;Button Caption || InfoType;VariableName;ParameterText || See full documentation below.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--d</nowiki> || 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. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--%</nowiki> || 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. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--*</nowiki> || 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.<br />
|}<br />
<br />
== ScriptCard Statement Type Details ==<br />
The sections below detail the individual statement types supported by ScriptCards<br />
<br />
=== Comment (--/) ===<br />
<br />
A --/ statement is ignored by the ScriptCards parser. You can use this type of statement to add comments and informational text to your script. <br />
<br />
Example:<br />
<pre><br />
!script {{<br />
--/|Script Name : Fireball<br />
--/|Purpose : Allow the player to cast a fireball and blow stuff up!<br />
.<br />
.<br />
.<br />
}}<br />
</pre><br />
<br />
=== Set Parameter (--#) ===<br />
<br />
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.<br />
<br />
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.<br />
<br />
'''''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.'''''<br />
<br />
Examples:<br />
<pre><br />
--#title|Magic Missile<br />
--#leftsub|Level 1 Spell<br />
--#rightsub|Force Damage<br />
</pre><br />
<br />
The three examples above set the “title”, “leftsub”, and “rightsub” values for the card to the content value for the line. <br />
<br />
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.<br />
Settings Lines do not produce output lines on the card.<br />
<br />
The following settings are available (note that parameter names are ''not'' case sensitive):<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Name !! Effect/Use !! Default Value !! Type<br />
|-<br />
| 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<br />
|-<br />
| allowplaintextinrolls || If set to a non-zero value, plain character text in rolls will be copied to the roll text || 0 || Per-Line<br />
|-<br />
| bodyFontFace || Name of the font used in the card rows || Helvetica || Global<br />
|-<br />
| bodyFontSize || Size of the text in the card rows || 14px || Global<br />
|-<br />
| bodybackgroundimage || Specify an image (content for a CSS background-image tag) for the body area || none || Global<br />
|-<br />
| buttonBackground || Background color for buttons created with [button][/button] || #1C6EA4 || Per-Line<br />
|-<br />
| buttonBorderColor || Border (outline) color for buttons created with [button][/button] || #999999 || Per-Line<br />
|-<br />
| buttonFontFace || Font Family specifier for captions on buttons created with [button][/button] || Tahoma || Per-Line<br />
|-<br />
| buttonFontSize|| Text size for captions on buttons created with [button][/button] || x-small || Per-Line<br />
|-<br />
| buttonTextColor|| Text color of labels on buttons created with [button][/button] || #FFFFFF || Per-Line<br />
|-<br />
| 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<br />
|-<br />
| deferralcharacter || Changes the meta script deferral sequence to the specified value || ^ || Per-Line<br />
|-<br />
| diceFontColor|| Color of the dice created with the [d4] [d6], etc. formatting markers || #1C6EA4 || Per-Line<br />
|-<br />
| dicefontsize || Size of the dice created with the [d4] [d6], etc. formatting markers || 3.0em || Per-Line<br />
|-<br />
| 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<br />
|-<br />
| disablerollprocessing || If set to a non-zero value, --= lines will not process dice rolls strings || 0 || Per-Line<br />
|-<br />
| emoteBackground || Background color of the emote area || #f5f5ba || Global<br />
|-<br />
| emoteFont || Name of the font used in emote area (above the title of the output card) || Georgia || Global<br />
|-<br />
| emoteFontColor || Color of the font in the emote area || None (Empty) || Global<br />
|-<br />
| emoteFontSize || Size of the font used in the emote area || 14px || Global<br />
|-<br />
| emoteFontWeight || Font weight for the font in the emote area || bold|| Global<br />
|-<br />
| emoteState || If set to anything other than "visible", the emote portion of the card will not be displayed || visible || Global<br />
|-<br />
| emoteText || Text to display in the emote portion of the card || None (Empty) || Global<br />
|-<br />
| emotefont || Name of the font used in the emote text area || font-family: Georgia, serif; font-weight: bold; || Global<br />
|-<br />
| evenRowBackground || Hex code for the background color for even rows || #eeeeee || Per-Line<br />
|-<br />
| evenRowFontColor || Hex code for the text color for even rows || #000000 || Per-Line<br />
|-<br />
| evenrowbackgroundimage || Specify an image (content for a CSS background-image tag) for the even card rows || none || Per-Line<br />
|-<br />
| executionlimit || Maximum number of script lines the interpreter will try to execute. This prevents "infinite loop" sandbox crashes || 40000 || Global<br />
|-<br />
| hideCard || If set to any non-default value, the entire card output will be suppressed || 0 || Global<br />
|-<br />
| 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<br />
|-<br />
| 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<br />
|-<br />
| lineheight || Vertical size of each line on the output card || normal || Per-Line<br />
|-<br />
| nominmaxhighlight || If set to anything other than "0", rolls will not display crit/fumble/mixed highlight colors. || 0 || Per-Line<br />
|-<br />
| norollhighlight || If set to anything other than "0", rolls will not be formatted (plain numbers) but will still get a tooltip with details ('''''v1.3.6b+''''') || 0 || Per-Line<br />
|-<br />
| oddRowBackground || Hex code for the background color for even rows || #d0e4f5 || Per-Line <br />
|-<br />
| oddRowFontColor || Hex code for the text color for odd rows || #000000 || Per-Line<br />
|-<br />
| oddrowbackgroundimage || Specify an image (content for a CSS background-image tag) for the odd crd rows || none || Per-Line<br />
|-<br />
| reentrant || Used to name a script for rentrant button use || 0 || Global<br />
|-<br />
| 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)0 || Global<br />
|-<br />
| rollhilightlineheight || Determines the height of the hilight box placed around roll results ('''''1.4.2+''''') || 1.0em || Per-Line<br />
|-<br />
| roundUp || If set to a non-default value, integer division will round up instead of down || 0 || Per-Line<br />
|-<br />
| showfromfornonwhispers || If set to a non-zero value, will include the sender on cards that aren't whispered || 0 || Global<br />
|-<br />
| 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<br />
|-<br />
| subtitleFontColor || Color of the text in the subtitle areas || #FFFFFF || Global<br />
|-<br />
| subtitleFontFace || Name of the font used on the subtitle sections || Tahoma || Global<br />
|-<br />
| subtitleFontSize || Size of the subtitle font || 13px || Global<br />
|-<br />
| subtitleSeperator || The character(s) that will be placed between leftsub and rightsub || <nowiki>&#x2666</nowiki>; || Global<br />
|-<br />
| tableBorderRadius || CSS specifier for how rounded the borders of the output card are. Use "0px;" for square borders || 6px; || Global<br />
|-<br />
| tableShadow || CSS specifier for the drop shadow under the output card || 5px 3px 3px 0px #aaa; || Global<br />
|-<br />
| tablebgcolor || Background color of the whole card. '''''Normally not visible''''' || #EEEEEE || Global<br />
|-<br />
| tableborder || Color of the border that surrounds the whole card || 2px solid #000000; || Global<br />
|-<br />
| 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<br />
|-<br />
| timezone || IANA Specifier for the local time zone, used in system/date functions || merica/New_York || Per-Line<br />
|-<br />
| title || Text displayed in the title area of the card || ScriptCards || Global<br />
|-<br />
| titleCardBackground || A hex color code representing the background color of the title area. || #1c6ea4 || Global<br />
|-<br />
| titleFontColor || Color of the text on the card title || #FFFFFF || Global<br />
|-<br />
| titleFontFace || Name of the font used on the title area || Contrail One || Global<br />
|-<br />
| titleFontLineHeight || Line spacing on the title area || 1.2em || Global<br />
|-<br />
| titleFontSize || Size of the title font || 1.2em || Global<br />
|-<br />
| titlecardbackgroundimage || Specify an image (content for a CSS background-image tag) for the title card area || none || Global<br />
|-<br />
| titlecardbottomborder || Border CSS specifier for the bottom of the title card area || 2px solid #444444; || Global<br />
|-<br />
| titlecardgradient || If set to non-zero value, will place a vertical gradient on the title card area || 0 || Global<br />
|-<br />
| usehollowdice || If set to a non-zero value, the hollow/outline versions of the dice fonts will be used || 0 || Per-Line<br />
|-<br />
| whisper|| Comma separated list of who to whisper the output to. Use "gm" for [[GM|GMs]] and "self" for the sender || none || Global|}<br />
|}<br />
<br />
''Setting Lines do not produce output lines on the card''<br />
<br />
=== Direct Output (--+) ===<br />
<br />
A direct output line display 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.<br />
<br />
Examples of Direct Output lines:<br />
<pre><br />
--+Hello|World<br />
--+Attack|The monster rolls [$Attack] to hit!<br />
--+Damage|@{target|token_name} is hit for [$Damage] [#3333AA][b]frost[/b][/#] damage.<br />
</pre><br />
<br />
Direct Output lines support inline formatting, roll variable replacement, character attribute references, and procedure variables.<br />
<br />
=== GM Output (--*) ===<br />
<br />
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. <br />
<br />
Example:<br />
<pre><br />
--+PlayerLine|This line is shown on the public card<br />
--*GMLine|This line will only be shown to GMs, on a separate card.<br />
</pre><br />
<br />
=== Roll Variable Assignment (--=) ===<br />
<br />
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.<br />
<br />
'''''All components of a roll equation should be separated with spaces.'''''<br />
<br />
Examples:<br />
<pre><br />
--=MissileDamage|1d4 + 1<br />
--=Attack|1d20 + @{selected|strength_mod} [STR] + @{selected|pb} [PROF]<br />
</pre><br />
<br />
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. Text enclosed in square brackets ([]) is considered "flavor text" and will be added to the result text but does not impact the roll result.<br />
<br />
The following dice formats are supported:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Format Pattern !! Example !! Description<br />
|-<br />
| XdY || 3d8 || Simple format. Roll a Y-sided die X times<br />
|-<br />
| XdYkhZ || 2d20kh1 || Roll Y-sided die X times and keep the highest Z number of dice<br />
|-<br />
| XdYklZ || 4d6kl3 || Roll Y-sided die X times and keep the lowest Z number of dice <br />
|-<br />
| XdY>Z || 5d6>3 || Roll Y-sided die X times and count a 1 for each roll greater than Z <br />
|-<br />
| XdY<Z || 5d6<3 || Roll Y-sided die X times and count a 1 for each roll less than Z <br />
|}<br />
<br />
'''''Note: The dice formulae below are supported in the development version of ScriptCards and will be merged with the table above when activated on OneClick'''''<br />
::{| class="wikitable"<br />
|-<br />
! Format Pattern !! Example !! Description<br />
|-<br />
| 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<br />
|-<br />
| 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<br />
|-<br />
| 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)<br />
|-<br />
| 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<br />
|}<br />
<br />
The following operators are supported in a roll equation:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Operator !! Operation<br />
|-<br />
| + || Addition <br />
|-<br />
| - || Subtraction <br />
|-<br />
| * || Multiplication <br />
|-<br />
| / || Division <br />
|-<br />
| \ || Integer Division (Rounds down) <br />
|-<br />
| % || Modulo (Remainder of Divison)<br />
|}<br />
<br />
Roll Variables can be accessed at any time after they have been created by using the [$VariableName] format, with the following optional modifiers:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Modifier !! Meaning<br />
|-<br />
| No modifier || In a Direct Output Line (<nowiki>--+</nowiki>) 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<br />
|-<br />
| .Total || The end result of the roll equation as an unformatted number <br />
|-<br />
| .Base || The cumulative result of any dice rolled in the Roll Text (Numeric modifiers are not included) <br />
|-<br />
| .Ones || The number of dice in the roll that came up as 1s <br />
|-<br />
| .Aces || The number of dice in the roll that came up as the maximum number on the die <br />
|-<br />
| .Odds || The number of dice in the roll that came up with an odd number <br />
|-<br />
| .Evens || The number of dice in the roll that came up with an even number <br />
|-<br />
| .RollText || The raw text of the roll that was use to generate the results <br />
|-<br />
| .Text || A text representation of the results of the roll, including the numbers rolled for each die <br />
|-<br />
| .tableEntryText || The text portion of the result of a table roll<br />
|-<br />
| .tableEntryImgURL || The image source portion of the result of a table roll<br />
|-<br />
| .tableEntryValue || Numeric value of tableEntryText (via parseInt). If a non-numeric value, will be 0<br />
|-<br />
| .Raw || The total numeric result without any formatting, even if placed somewhere formatting would normally be done. <br />
|}<br />
<br />
Examples:<br />
<pre><br />
--+Total Damage|[$MissileDamage.Total] (roll was 1d4+1)<br />
--+Base Damage|[$MissileDamage.Base] (without the +1)<br />
--=Attack|1d20 + @{selected|strength_mod} [STR] + @{selected|pb} [PROF] + [$BlessBonus] [Bless]<br />
</pre><br />
<br />
In this case, 1d4 will be rolled and stored in “BlessBonus”, which can then be used in the Attack line.<br />
<br />
'''''Mathematical Functions in Roll Expressions '''''<br />
<br />
The ScriptCards roll parser works from left to right, always maintaining a current value and applying whatever comes next to the total. The following in-line functions to the roll parser. These are:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Expression !! Meaning<br />
|-<br />
| {ABS} || Absolute Value<br />
|-<br />
| {CEIL} || Ceiling value (round up to the next whole number)<br />
|-<br />
| {FLOOR} || Floor value (round down to the next whole number)<br />
|-<br />
| {ROUND} || Round value (round up if the decimal portion is greater than 0.5, otherwise round down)<br />
|-<br />
| {NEGATE} || Multiply the value by negative one.<br />
|-<br />
| {SQRT} || Take the square root of the running value. ('''''1.4.1+''''')<br />
|-<br />
| {SQUARE} || Square the running value. ('''''1.4.2+''''')<br />
|-<br />
| {CUBEROOT} || Take the cube root of the running value. ('''''1.4.2+''''')<br />
|-<br />
| {CUBE} || Cube the running value. ('''''1.4.2+''''')<br />
|-<br />
| {SIN} || Return the SIN of running value. ('''''1.4.2+''''')<br />
|-<br />
| {COS} || Return the COS of running value. ('''''1.4.2+''''')<br />
|-<br />
| {TAN} || Return the TAN of running value. ('''''1.4.2+''''')<br />
|-<br />
| {ASIN} || Return the ASIN of running value. ('''''1.4.2+''''')<br />
|-<br />
| {ACOS} || Return the ACOS of running value. ('''''1.4.2+''''')<br />
|-<br />
| {ATAN} || Return the ATAN of running value. ('''''1.4.2+''''')<br />
|}<br />
<br />
<br />
'''''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 <nowiki>[[ ]]</nowiki> 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.<br />
<br />
'''''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.<br />
<br />
'''Rolling on Rollable Tables'''<br />
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.<br />
<br />
''Roll Variable Lines do not produce output lines on the card.''<br />
<br />
=== String Variable Assignment (--&) ===<br />
<br />
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:<br />
<br />
<pre><br />
--&MyText|Hello<br />
</pre><br />
<br />
Here, we assign the text "Hello" to the string variable named MyText. You can also append text to a string variable by prefixing the content with a + sign:<br />
<br />
<pre><br />
--&MyText|+ World<br />
</pre><br />
<br />
If run after the statement above, MyText will now contain "Hello World".<br />
<br />
String variables can be referenced using the syntax [&variablename]<br />
<br />
=== Call API (--@) ===<br />
<br />
ScriptCards can use a Call API instruction to execute other API commands. The Tag contains the API 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 API command is executed.<br />
<br />
Examples:<br />
<pre><br />
--@eh|list<br />
--@alter|_target|@{target|token_id} _bar|3 _amount|-[$Damage]<br />
</pre><br />
<br />
In the first example above, the command <code>!eh list</code> will be executed, calling [[EncounterHelper]]. In the second, {{fpl|1216260/ AlterBars}} is called to modify a token's Bar 3 value.<br />
<br />
'''''Note:''''' When ScriptCards (or any API script) runs other API 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).<br />
<br />
See [[API:Script Index]] for more options.<br />
<br />
=== Branch Label (--:) ===<br />
<br />
A branch label defines a line in your code that can be reached by one of the branching instructions (<nowiki>--^</nowiki>, <nowiki>--></nowiki>, or <nowiki>--?</nowiki>). The Tag serves as the label name, and must be unique on the card.<br />
<br />
The vertical bar (|) separator must be present, but the content portion of the line is unused and can be treated as a comment.<br />
<br />
Examples:<br />
<pre><br />
--:MyLoop|<br />
--:CriticalHit|Will jump here if we roll a critical hit!<br />
</pre><br />
<br />
''A Branch Label line does not produce an output line on the card.''<br />
<br />
=== Branch (--^) === <br />
<br />
A Branch line 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.<br />
<br />
Examples:<br />
<pre><br />
--^MyLoop|Jumps to MyLoop<br />
--^SkipCrit|We didn't crit, so skip the Crit code<br />
</pre><br />
<br />
''A Branch line does not produce an output line on the card.''<br />
<br />
=== Call Procedure (-->) ===<br />
<br />
Similar to a branch, a Call Procedure (sometimes knows 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 (<nowiki>--<</nowiki>) 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 (;).<br />
<br />
Examples:<br />
<pre><br />
-->FixFormat|#3333FF;#999999<br />
</pre><br />
<br />
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%].<br />
<br />
=== Return (--<) ===<br />
<br />
A return instruction marks the end of a Gosub procedure. 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.<br />
<br />
Examples:<br />
<pre><br />
--<|<br />
--<|End of MySub<br />
</pre><br />
<br />
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.<br />
<br />
=== Conditional Statement (--?) ===<br />
<br />
A conditional statement contains some equation in the Tag that will be evaluated. '''''If any part of the comparison can/does contain a space, it needs to be surrounded by double quotes'''''<br />
<br />
Based on the true/false result of the evaluation, one of two execution paths will be taken. These execution paths are detailed in the content section of the statement. The "if true" path is specified first (directly after the vertical bar), and the "if false" path is specified after it, also separated by a vertical bar.<br />
<br />
Example:<br />
<pre><br />
--?[$AttackRoll.Total] -ge [$TargetAC]|Hit|Miss<br />
</pre><br />
<br />
'''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.'''<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Branch Format !! Meaning<br />
|-<br />
| Label || If just a label is specified, execution will branch to that label when the comparison is matched.<br />
|-<br />
| >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 <br />
|-<br />
| =VariableName || The roll variable "VariableName" will be assigned the value following a semicolon (ex: --?1 -eq 1|=Roll;1d20)<br />
|-<br />
| &VariableName || The string variable "VariableName" will be assigned the value following a semicolon (ex: --?1 -eq 1|&Result;Hit|&Result;Miss)<br />
|-<br />
| % or %! || The current for...next loop will perform the "next" action (%) or will break out (%!) <br />
|-<br />
| [ || Code block (see below)<br />
|}<br />
<br />
Examples:<br />
<pre><br />
--?[$AttackRoll.Base] -eq 20|CriticalHit<br />
--?[$AttackRoll.Base] -eq 1|>Fumble;@{selected|dexterity_mod}<br />
--?"@{target|npc_type}" -inc "undead"|&MonsterType;Undead|&MonsterType;Not Undead<br />
--?[$Attack.Total] >= [$ArmorClass]|>Hit|>Miss<br />
</pre><br />
<br />
In the first example, if the Base value of AttackRoll is a 20 (natural 20 on the die) execution will branch to the CriticalHit label.<br />
<br />
In the second example, 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%].<br />
<br />
The third example looks for the word "undead" in the npc_type attribute of the targeted character. If it exists in the text, the MonsterType string variable will be set to "Undead", otherwise it will be set to "Not Undead". <br />
<br />
The final example would call 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.<br />
<br />
''Text that does/may contain a space should be enclosed in double quotes.''<br />
<br />
The following comparison operators are available:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Comparator !! Meaning<br />
|-<br />
| -eq || Equal To <br />
|-<br />
| -eqi || Case insensitive Equal To <br />
|-<br />
| -ne || Not Equal To <br />
|-<br />
| -nei || Case insensitive Not Equal To <br />
|-<br />
| -gt || Greater Than <br />
|-<br />
| -ge || Greater Than or Equal To <br />
|-<br />
| -lt || Less Than <br />
|-<br />
| -le || Less Than or Equal To <br />
|-<br />
| -inc || Includes (text strings). <br />
|-<br />
| -ninc || Does Not Include (text strings). <br />
|}<br />
<br />
Multi-part conditionals are supported with -and and -or as separators. For example:<br />
<br />
<pre><br />
--?[$Attack.Total] -ge @{target|npc_ac} -and [$Attack.Base] -ne 20|HitButNotCrit<br />
</pre><br />
<br />
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):<br />
<br />
true AND false OR true<br />
<br />
Will be evaluated as true. The first two (true and false) will be false, but then false OR true will be true.<br />
<br />
Conversely:<br />
<br />
true or false and false<br />
<br />
Will be false, because the first true and false will evaluate to true, and then true and false will be false.<br />
<br />
'''CODE BLOCKS'''<br />
<br />
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.<br />
<br />
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:<br />
<br />
<pre><br />
!script {{<br />
--=Roll|1d2<br />
--+Roll|[$Roll]<br />
--?[$Roll.Total] -eq 2|[<br />
--&Value|Yep!<br />
--+|We are inside the TRUE portion of the block<br />
--]|[<br />
--&Value|Nope<br />
--+|We are inside the FALSE portion of the block<br />
--]|<br />
--+After|the blocks!<br />
--+Value|[&Value]<br />
}}<br />
</pre><br />
<br />
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 --]|. <br />
<br />
At this time, blocks cannot be nested, and can only be created as part of a conditional (--[ is not a valid statement type)<br />
<br />
''A conditional statement does not produce a line of output on the card.''<br />
<br />
=== Case Statement (--c) ===<br />
<br />
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 (:). Each match condition includes a branch label that will be used if the test value matches the item. 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:<br />
<br />
<pre><br />
!script {{<br />
--#title|Case Statement Testing<br />
--=Roll|1d4<br />
--C[$Roll.Total]|1:>One;[$Roll]|2:>Two;[$Roll]|3:>Three;[$Roll]|4:>Four;[$Roll]<br />
--X|<br />
<br />
--:One| --+Value|was One ([%1%]) --<|<br />
--:Two| --+Value|was Two ([%1%]) --<|<br />
--:Three| --+Value|was Three ([%1%]) --<|<br />
--:Four| --+Value|was Four ([%1%]) --<|<br />
}}<br />
</pre><br />
<br />
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 variable as a parameter.<br />
<br />
=== Save and Load (--s and --l) ===<br />
<br />
This statement pair is used to either store (--s) or load (--l) data from persistent storage. Items stored in persistent storage remain between card rolls and between Roll20 sessions. There are two types of data that can be stored: settings and roll variables. <br />
<br />
Examples:<br />
<br />
<pre><br />
--Ssettings|GreenStyle<br />
--Srollvariables|FirstCardVars<br />
</pre><br />
<br />
In this case, the tag for the statement determines what type of item is being saved (settings or rollvariables). When saving settings, all non-default settings are written to the named setting storage value. When Roll Variables are saved, all variables that currently exist will be saved to the named storage value.<br />
<br />
Loading stored items simply requires the same command with the --l statement type:<br />
<br />
<pre><br />
--Lsettings|GreenStyle<br />
--Lrollvariables|FirstCardVars<br />
</pre><br />
<br />
When loading settings, all stored settings will be applied to the current card settings. You can override settings by changing them after the load.<br />
<br />
When loading roll variables, the saved variables will be added to (or overwrite if they have the same name) any variables on the current card. This means it is safe to create roll variables before the load statement.<br />
<br />
'''Practical Uses'''<br />
The major intended use of persistent storage is for storing card formats for use in later scripts. For example, the following script:<br />
<br />
<pre><br />
!scriptcard {{<br />
--#titlecardbackground|#22CC22<br />
--#oddrowbackground|#cceecc<br />
--#evenrowbackground|#99ee99<br />
--Ssettings|@{selected|token_name}<br />
}}<br />
</pre><br />
<br />
Would save the titlecardbackground, oddrowbackground, and evenrowbackground settings to a saved list named after the selected token's name. When creating cards for that token to run later, you could include the line:<br />
<br />
<pre><br />
--Lsettings|@{selected|token_name}<br />
</pre><br />
<br />
To load all of the settings at once. By creating these setting sets for each character, you can specify a different color scheme for each character that can then be used in cards with a single formatting line.<br />
<br />
There is a supplemental ! command added to support saved settings:<br />
<br />
<pre><br />
!sc-liststoredsettings<br />
</pre><br />
<br />
Will produce a list of all stored setting names, with buttons to list the setting values stored in each group and a button to delete groups as needed.<br />
<br />
=== Visual Effects (--v) ===<br />
<br />
The --v statement can be used to create visual effects on the tabletop. The tag portion of the statement can be either "token" or "betweentokens". The content portion of the statement contains the required parameters for the effect generation, separated by spaces. If the effect is "none", no effect will be played. If any other value that doesn't match a Roll20 effect name will result in a burst-fire effect.<br />
<br />
For "token" effects, the parameters are the token id for the token the effect happens on, followed by the effect specifier.<br />
<br />
Example:<br />
<pre><br />
--vtoken|@{selected|token_id} burst-fire<br />
</pre><br />
<br />
For "betweentoken" effects, the parameters are the source token id, the target token id, and the effect specifier.<br />
<br />
Example:<br />
<pre><br />
--vbetweentokens|@{selected|token_id} @{target|token_id} beam-magic<br />
</pre><br />
<br />
'''''Version 1.2.8+'''''<br />
<br />
An additional effect specifier, "point" is available in 1.2.8+. This specifier allows you to create a visual effect at a designated X/Y pixel coordinate. Future updates will add custom-vfx support to this option. The parameters are the X and Y coordinates and the effect descriptor. As of version 1.2.9, you can also use custom effect specifiers with Point effects:<br />
<br />
<pre><br />
--vpoint|150 200 burst-fire<br />
</pre><br />
<br />
=== Echo to Chat (--e) ===<br />
<br />
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.<br />
<br />
Example:<br />
<pre><br />
--eThe Ghost|/em hovers around @{selected|character_name}... BOO!<br />
</pre><br />
<br />
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).<br />
<br />
'''''Whispering'''''<br />
<br />
You can use the echo statement to send a whisper, but there's a trick to it. If you execute this code here:<br />
<br />
<pre><br />
--eThe Ghost|/w ExamplePlayerName Boo.<br />
</pre><br />
<br />
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.<br />
<br />
So, in conclusion, it's best to use something like this when you're sending a whisper:<br />
<br />
<pre><br />
!script {{<br />
--#hidecard|1<br />
--&sender|The Ghost<br />
--&receiver|ExamplePlayerName<br />
--&message|Boo.<br />
--e[&sender]|/w [&receiver] [&message]<br />
--eScriptCards|/w gm **Whispered from [&sender] to [&receiver]:** [&message] <br />
}}<br />
</pre><br />
<br />
This will ensure that the message appears in your chat feed as well.<br />
<br />
=== Repeating Section Access (--R) ===<br />
<br />
ScriptCards (as of v0.0.13) supports accessing repeating section rows on a character sheet with the --R statement type. <br />
<br />
There are three basic commands you can use with --R, and they are specified by the tag used:<br />
<br />
<pre><br />
--Rfind|characterid;EntryName;SectionPrefix;SearchField<br />
</pre><br />
<br />
This is the most direct way to access a repeating section row. Supplying the character ID, followed by what you are looking for (Greatsword, for example), followed by the character sheet's section prefix (repeating_attack), followed by the field to check what you are searching for (atkname) will load the matching section (if found) into the script parsers memory. For example:<br />
<br />
<pre><br />
--Rfind|@{selected|character_id};Greatsword;repeating_attack;atkname<br />
</pre><br />
<br />
Will look at the character's "repeating_attack" section for an entry with an atkname value equal to "Greatsword". Similarly:<br />
<br />
<pre><br />
--Rfind|@{selected|character_id};Bite;repeating_npcaction;name<br />
</pre><br />
<br />
Will look for a "Bite" action on an NPC's action list.<br />
<br />
<pre><br />
--Rfirst|characterid;section prefix<br />
</pre><br />
<br />
This form of the --R command will look at all of the entries in the specified repeating section and load the first one into memory:<br />
<br />
<pre><br />
--Rfirst|@{selected|character_id};repeating_attack<br />
</pre><br />
<br />
Would load the character's first "repeating_attack" row into memory.<br />
<br />
<pre><br />
--Rnext|<br />
</pre><br />
<br />
No parameters are required for --Rnext, which loads the next entry in the list that was obtained with "first" into memory.<br />
<br />
However a row is obtained, it will be parsed to replace any attribute references (ie, @{level}) with the corresponding character attribute.<br />
<br />
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".<br />
<br />
You can reference repeating attribute data using the syntax [*R:attributename] syntax (similar to referencing standard character attributes).<br />
<br />
Here are some examples:<br />
<br />
Display the details of the "Greatsword" PC attack:<br />
<br />
<pre><br />
!script {{<br />
--Rfind|@{selected|character_id};Greatsword;repeating_attack;atkname<br />
--+Attack Name|[*R:atkname]<br />
--+Base Damage|[*R:dmgbase]<br />
}}<br />
</pre><br />
<br />
[[File:Scriptcards repeating greatsword.png|Repeating Greatsword Attack]]<br />
<br />
List all of the actions an NPC can take (just actions, not legendary, etc.)<br />
<br />
<pre><br />
!script {{<br />
--#title|NPC Actions<br />
--#leftsub|@{selected|token_name}<br />
--Rfirst|@{selected|character_id};repeating_npcaction<br />
--:DisplayLoop|<br />
--?"[*R:name]" -eq NoRepeatingAttributeLoaded|Done<br />
--+Action:|[*R:name] [*R:attack_damage] [*R:attack_damagetype]<br />
--?"[*R:attack_damage2]" -eq ""|NoSecondaryDamage<br />
--+ |[*R:attack_damage2] [*R:attack_damagetype2]<br />
--:NoSecondaryDamage|<br />
--Rnext|<br />
-->DisplayLoop| <br />
--:Done|<br />
}}<br />
</pre><br />
<br />
[[File:Scriptcards repeating npcactions.png]]<br />
<br />
In the script above, we get the "first" repeating_npcaction and display information about it. We then execute "next" and repeat until we run into "NoRepeatingAttributeLoaded".<br />
<br />
'''''Special debugging command: dump'''''<br />
<pre><br />
--Rdump|<br />
</pre><br />
<br />
The "dump" command will list all of the attributes ScriptCards knows about for the currently loaded repeating row to the API Console Log.<br />
<br />
=== Assign Variable to Built-In Function (--~) ===<br />
<br />
ScriptCards has the ability to run a function built into the API script and return the results to a variable. Some functions return roll variables, while others return strings. See the function table below for details. The format is:<br />
<br />
--~VariableName|function;param1;param2;param3;...<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Function Name !! Parameters !! Description<br />
|-<br />
| distance || token_A_ID;token_B_ID || Calculate the Chebyshev distance in grid units between two tokens. This is the measurement scheme D&D 4E/5E use for diagonal distance measurement<br />
|-<br />
| euclideandistance || token_A_ID;token_B_ID || Calculate the Euclidean distance between two tokens. This is essentially the Pythagorean theorem in action. Returns the result in grid units.<br />
|-<br />
| euclideanpixel || token_A_ID;token_B_ID || Calculate the Euclidean distance between two tokens and returns the result is pixels instead of grid units. <br />
|-<br />
| euclideanlong || token_A_ID;token_B_ID || 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 is calculated instead of before. More accurate over long distances. <br />
|-<br />
| manhattandistance || token_A_ID;token_B_ID || Also called "taxicabdistance" (which is an acceptable function name), this measures to how-many-over, how-many-up/down distance, disallowing diagonal movement.<br />
|-<br />
| getselected || none || 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 the first selected token, VariableName2 the second, etc.<br />
|}<br />
<br />
'''''Functions with Sub Functions'''''<br />
<br />
Most ScriptCards functions are grouped into set as sub functions. The table below lists the major functions and their sub functions.<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Function Name !! Sub Function !! Parameters !! Return Type !! Description<br />
|-<br />
| array || define || arrayname;value1;value2;... || none || Creates an array called "arrayname" and adds value1, value2, etc. to the array<br />
|-<br />
| array || sort || arrayname || none || Sorts the specified array in place in ascending order<br />
|-<br />
| array || add || arrayname;value1;value2;... || none || Adds value1, value2, ... to the existing array "arrayname"<br />
|-<br />
| array || remove || arrayname;value1;value2;... || none || Removes value1, value2, ... from the existing array "arrayname". Resets the array index to 0.<br />
|-<br />
| array || replace || arrayname;currentvalue;newvalue || none || Replaces all occurrences of "currentvalue" in "arayname" with "newvalue"<br />
|-<br />
| array || setatindex || arrayname;index;newvalue || none || Replaces the array item at index "index" with "newvalue"<br />
|-<br />
| array || getindex || arrayname || stringVariable || Retrieves the current index in "arrayname" and stores it in the supplied string variable<br />
|-<br />
| array || setindex || arrayname;newindex || none || Sets the current index in array "arrayname" to "newindex"<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| array || removeat || arrayname;indexposition || none || Removes the item at index "indexposition" from "arrayname". Resets the current array index to 0.<br />
|-<br />
| array || indexof || arrayname;searchvalue || stringVariable || Searches the array "arrayname" for and item with the value of "searchvalue" and, if found, returns the index of the first matching value or "ArrayError" if not found<br />
|-<br />
| array || getlength || arrayname || stringVariable || Returns the number of items in array "arrayname"<br />
|-<br />
| array || pagetokens || arrayname;tokenid;(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. 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.)<br />
|-<br />
| 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.<br />
|-<br />
| array || stringify || arrayname || stringVariable || Returns all of the items in "arrayname" as a string separated by semicolons (;)<br />
|-<br />
| array || fromstring || arrayname || delimiter;string || Creates an array from "string", splitting "string" on "delimiter" to separate the items<br />
|-<br />
| array || statusmarkers|| arrayname;tokenid || none|| Creates an array (arrayname) of the active statusmarkers (sometimes called Token Markers) for the specified tokenid<br />
|-<br />
| math || angle || math;angle;tokenid;tokenid|| rollVariable || Calculates the angle between two tokens and returns the value in degrees<br />
|-<br />
| math || ceil || math;ceil;value || rollVariable || Rounds '''value''' up to the next integer, dropping any decimal portion of the number<br />
|-<br />
| math || clamp || math;clamp;value;lowerBound;upperBound || rollVariable || Returns '''value''', but restricted to the range of '''loweBound''' and '''upperBound'''.<br />
|-<br />
| math || floor || math;floor;value || rollVariable || Rounds '''value''' down, dropping any decimal portion of the number<br />
|-<br />
| math || max || math;max;valueA;valueB || rollVariable || Returns the larger of '''valueA''' vs '''valueB'''<br />
|-<br />
| math || min || math;min;valueA;valueB || rollVariable || Returns the smaller of '''valueA''' vs '''valueB'''<br />
|-<br />
| math || round || math;round;value || rollVariable || Rounds '''value''' to the nearest integer<br />
|-<br />
| string || length || string;length;stringValue || rollVariable || Returns the length of '''stringValue''' in characters<br />
|-<br />
| string || before || string;before;searchText;stringValue || stringVariable || Searches '''stringValue''' for '''searchText''' and returns the portion of '''stringValue''' prior to that text<br />
|-<br />
| string || after || string;after;searchText;stringValue || stringVariable || Searches '''stringValue''' for '''searchText''' and returns the portion of '''stringValue''' after that text<br />
|-<br />
| string || left || string;left;count;stringValue || stringVariable || Returns the leftmost '''count''' characters of '''stringValue'''<br />
|-<br />
| string || right || string;right;count;stringValue || stringVariable || Returns the rightmost '''count''' characters of '''stringValue'''<br />
|-<br />
| string || replace || string;replace;searchText;replaceText;stringValue || stringVariable || Replaces '''searchText''' in '''stringValue''' with '''replaceText''' and returns the resulting string<br />
|-<br />
| string || replaceall || string;replace;searchText;replaceText;stringValue || stringVariable || Replaces all intances of '''searchText''' in '''stringValue''' with '''replaceText''' and returns the resulting string '''''Requires 1.2.9+'''''<br />
|-<br />
| string || trim || string;trim;stringValue || stringVariable || Removes leading and trailing spaces from stringValue and returns the result. <br />
|-<br />
| string || substring || string;substring;start;count;stringValue || stringVariable || Returns '''count''' characters starting at '''start''' from '''stringValue'''<br />
|-<br />
| 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.<br />
|-<br />
| string || tolowercase || string;tolowercase;stringValue || stringVariable || Converts the passed string to lower case and assigns to the passed variable name. <br />
|-<br />
| string || touppercase || string || stringVariable || Converts the passed string to upper case and assigns to the passed variable name. <br />
|-<br />
| 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. <br />
|-<br />
| 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.<br />
|-<br />
| 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'''.<br />
|-<br />
| turnorder || clear || none || none || Clears all entries from the {{Turn Tracker}}/Initiative<br />
|-<br />
| turnorder || addtoken || tokenid;trackervalue || none || Adds the token represented by "tokenid" to the initiative tracker with an initiavie value of "trackervalue"<br />
|-<br />
| turnorder || replacetoken || tokenid;trackervalue || none || Replaces the token represented by "tokenid" in the initiative tracker with an initiavie value of "trackervalue". Will add the token if it doesn't exist in the tracker.<br />
|-<br />
| turnorder || removetoken || tokenid || none || Removes the token represented by "tokenid" from the initiative tracker if it exists<br />
|-<br />
| turnorder || addcustom || textlabel;trackervalue || none || Add a custom text entry to the {{Turn Tracker}}/Initiative named "textlabel" with an initiative value of "trackervalue"<br />
|-<br />
| system || date || getdatetime || stringVariable || Returns the date time in the active timezone (see settings) <br />
|-<br />
| system || date || getdate || stringVariable || Returns the date in the active timezone (see settings) <br />
|-<br />
| system || date || gettime || stringVariable || Returns the time in the active timezone (see settings)<br />
|-<br />
| system || dumpvariables || "rolls", "string", or "array" || none || Dumps all of the defined variables of the indicated type to the console log<br />
|-<br />
| system || findability || system;findability;charactername;abilityname || stringVariable || Returns the object ID of the ability on the indicated character or "AbilityNotFound"<br />
|-<br />
|}<br />
<br />
Examples:<br />
<br />
<pre><br />
--~HowFarAway|distance;@{selected|token_id};@{target|token_id}<br />
</pre><br />
<br />
Returns the distance (Chebyshev) between the selected and target tokens and stores it in "HowFarAway".<br />
<br />
<pre><br />
--SelectedDudes|getselected<br />
</pre><br />
<br />
If 5 tokens were selected, 6 variables would be created: SelectedDudesCount (with a value of 5), SelectedDudes1, SelectedDudes2, SelectedDudes3, SelectedDudes4, SelectedDudes5.<br />
<br />
=== Information Request (--i) ===<br />
<br />
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.<br />
<br />
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.<br />
<br />
After the user has clicked the button and responded to the requests, ScriptCards will resume processing the script from where it left off.<br />
<br />
Here is an example “i” line:<br />
<br />
<pre><br />
--IScriptCards needs additional information to continue;Click to select a target and provide information|t;MyNewTarget;Missile1Target||q;MyNameIs;What is your name?<br />
</pre><br />
<br />
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.<br />
<br />
Supported information request types are “t” for target token, and “q” for query.<br />
<br />
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).<br />
<br />
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:<br />
<br />
<pre><br />
q;UserName;What is your name?|Fred|Bob|Sally|Nancy<br />
</pre><br />
<br />
Would have a dropdown menu with four choices.<br />
<br />
== Inline Formatting ==<br />
<br />
Inline formatting is processed on Direct Output lines only (--+ lines) and the following inline format markup is available:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Formatting Tags !! Description<br />
|-<br />
| [b]..[/b] || Bold the text between the markers <br />
|-<br />
| [i]..[/i] || Italicize the text between the markers <br />
|-<br />
| [u]..[/u] || Underline the text between the markers <br />
|-<br />
| [s]..[/s] || Strike-Thru the text between the markers <br />
|-<br />
| [c]..[/c] || Center alignment <br />
|-<br />
| [l]..[/l] || Left alignment <br />
|-<br />
| [r]..[/r] || Right alignment <br />
|-<br />
| [j]..[/j] || Full justification alignment <br />
|-<br />
| [#xxx]..[/#] or [#xxxxxx]..[/#] || Use a 3 or 6 digit hex code to colorize the text between the markers <br />
|-<br />
| [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, <code>[img width=128 height=128]</code> )<br />
|-<br />
| [button]caption::action[/button] || Create a button with the label "caption" that performs the action defined by "action". <br />
|-<br />
| [t] || Converted to HTML table tag. Text after the "t" will be included inside the tag (width, border, etc)<br />
|-<br />
| [/t] || Converted to HTML close table tag.<br />
|-<br />
| [tr] || Converted to HTML table row tag. Text after the "tr" will be included inside the tag<br />
|-<br />
| [/tr] || Converted to HTML close table row tag.<br />
|-<br />
| [td] || Converted to HTML table cell tag. Text after the "tr" will be included inside the tag<br />
|-<br />
| [/td] || Converted to HTML close table cell tag.<br />
|}<br />
<br />
== Variables ==<br />
<br />
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. While it is possible to assign both a string and a roll variable the same name, doing so will likely result in confusion when looking at the script later, so it is not recommended.<br />
<br />
String Variables are assigned with the --& statement and are referenced using [&variableName] notation.<br />
<br />
Roll Variables are assigned with the --= statement, and the assignment value is always processed by the ScriptCards Roll Processor (resolves dice rolls, etc.)<br />
<br />
There are a handful of variables assigned automatically when a ScriptCard is executed. These are all string variables, and are:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Variable !! Value<br />
|-<br />
| SendingPlayerID || Contains the object ID of the player that sent the macro<br />
|-<br />
| SendingPlayerName || Contains the display name of the player<br />
|-<br />
| SendingPlayerColor || Contains the color code associated with the player<br />
|-<br />
| SendingPlayerSpeakingAs || The contents of the "Speaking As" dropdown window<br />
|-<br />
| SendingPlayerIsGM || Contains 1 if the player is a GM, and 0 if the player is NOT a GM<br />
|}<br />
<br />
== Arrays ==<br />
<br />
Arrays are a special type of variable, and are managed by the function (<nowiki>--~</nowiki> command). All of the array function commands follow the same pattern:<br />
<br />
<pre>--~variableName|array;subcommand;arrayname;param1;param2;param3;...</pre><br />
<br />
Not all array commands return anything to "variableName". The function table above will specify the return type of the command if any.<br />
<br />
There are a couple of different ways to create an array:<br />
<br />
The '''define''' array subcommand creates (or recreates) an array and assigns it values - one for each included parameter after the array name. For example:<br />
<br />
<pre>--~|array;define;Fruits;mango;peach;strawberry;apricot;banana;apple</pre><br />
<br />
will create an array called '''Fruits''' with 6 elements in the order listed in the command (mango, peach, etc.)<br />
<br />
You can also use two other subcommands to create arrays based on tokens:<br />
<br />
<pre>--~Count|array;pagetokens;Everybondy;@{selected|token_id}</pre><br />
<br />
and<br />
<br />
<pre>--~Count|array;selectedtokens;Selected</pre><br />
<br />
In both cases, arrays of tokens will be created, and a string variable called "Count" will be set to the number of tokens in the array. The '''pagetokens''' command returns (by default) all of the tokens on the page that contains the token passed as the parameter after the array name. You can filter the tokens that "pagetokens" includes in the array by appending an optional parameter describing the type of token you are looking for:<br />
<br />
<pre>--~Count|array;pagetokens;Everybondy;@{selected|token_id};npc</pre><br />
<br />
Will return only tokens on the page that represent characters that do not have a ''controlledby'' parameter set. The available options are "all" (default), "char", "graphic", "pc", and "npc".<br />
<br />
The '''selectedtokens''' command returns an array with all of the tokens that were selected when the script was called.<br />
<br />
You can also use an arbitrary string to create an array, specifying a delimiter with the '''fromstring''' command:<br />
<br />
<pre><br />
--&names|Fred<br />
--&names|+,Sally<br />
--&names|+,Ted<br />
--&names|+,Joyce<br />
--~|array;fromstring;,;[&names]<br />
</pre><br />
<br />
The above example builds a comma-separated string and then uses "fromstring" to create an array with 4 elements from it, specifying the comma as the delimiter.<br />
<br />
Finally, you can use the '''statusmarkers''' command to create an array with one entry for each active status marker on a specified token:<br />
<br />
<pre>--~|array;statusmarkers;Conditions;@{selected|token_id}</pre><br />
<br />
will create an array with one entry for each status active on the selected token. The array elements will be the internal name of the status (if you are using custom status marker packs, the names will be specified in the marker pack).<br />
<br />
'''Traversing Arrays'''<br />
<br />
Each array keeps track of an internal index position (starting at 0). Several commands let you manage this index:<br />
<br />
*'''getindex''' returns the current index value<br />
*'''setindex''' sets the index to the specified location in the array<br />
*'''getlength''' returns the number of elements in the array<br />
*'''indexof''' returns the index location of the specified element<br />
<br />
Other commands let you retrieve values from the array:<br />
<br />
*'''getfirst''' sets the index to 0 and returns the value at that position<br />
*'''getnext''' advances the index by 1 and returns the new current value<br />
*'''getprevious''' reduces the index by 1 and returns the new current value<br />
*'''getlast''' sets the index to the last elements in the array and returns the new current value<br />
<br />
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.<br />
<br />
'''Manipulating Array Elements'''<br />
<br />
Several array commands deal with inserting, removing, and modifying elements:<br />
<br />
*'''add''' works just like define, except that it takes an existing array and adds elements to it based on the passed parameters<br />
*'''remove''' looks for items matching each passed parameter and removes them from the indicated array if they exist<br />
*'''removeat''' allows you to specify an index location in the array and remove the element at that position<br />
*'''replace''' searches an array for a value and replaces all occurrences of it with a new value (if found)<br />
*'''sort''' sorts the elements in the array in ascending order<br />
*'''strinfigy''' returns a string variable that includes each array element separated by semicolons (;) <br />
<br />
'''Referencing Array Elements'''<br />
<br />
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.<br />
<br />
<pre><br />
!script {{<br />
--~dummy|array;pagetokens;myarray;@{selected|token_id}<br />
--~count|array;getcount;myarray<br />
--+Total:|There are [&count] graphical objects on the page<br />
--~testvar|array;getfirst;myarray<br />
--:loop|<br />
--+Value|[*[&testvar]:character_name]<br />
--~testvar|array;getnext;myarray<br />
--?[&testvar] -ne ArrayError|loop<br />
--+Loop1|Is Done!<br />
}}<br />
</pre><br />
<br />
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:<br />
<br />
<pre><br />
!script {{<br />
--~dummy|array;pagetokens;myarray;@{selected|token_id}<br />
--~count|array;getcount;myarray<br />
--+Total:|There are [&count] graphical objects on the page<br />
--%loopCounter|1;[&count]<br />
--+Value|[*[@myarray([&loopCounter])]:character_name]<br />
--%|<br />
--+Loop|Is Done!<br />
}}<br />
</pre><br />
<br />
This line : <nowiki>--+Value|[*[@myarray([&loopCounter])]:character_name]</nowiki> uses [@arrayName(index)] format (inside a [*characterid:attribute] syntax) to perform the same task as running through the loop with the index.<br />
<br />
(Note: Additional examples are on the way...)<br />
<br />
== For...Next Loops ==<br />
<br />
For...Next loops in ScriptCards are supported with the with the --% statement type. A loop is defined by starting off with:<br />
<br />
<pre><br />
--%LoopCounter|<start>;<end>;[step]<br />
</pre><br />
<br />
The start and end values are required, while the step parameter is optional. If the step is omitted, it will be assumed to be 1. A string variable named after the line tag ("LoopCounter" in the case above) will be created and will hold the current iteration value for the loop. Here is a real example:<br />
<br />
<pre><br />
--%LoopCounter|1;10;1<br />
</pre><br />
<br />
This will begin a loop identified by "LoopCounter" that will start at 1, increasing by 1 each iteration (the step) until it has completed 10 executions.<br />
<br />
The "next" statement is simply <code>--%|</code>, with no tag or parameters. This indicates to ScriptCards that it should increment the counter and go back to the beginning of the loop. Extending the example above:<br />
<br />
<pre><br />
!script {{<br />
--%LoopCounter|1;10;1<br />
--=Roll|1d20<br />
--+Loop|Counter is [&LoopCounter], roll was [$Roll]<br />
--%|<br />
}}<br />
</pre><br />
<br />
The <code>--%!|</code> sequence will break out of the loop, no matter how many iterations are remaining.<br />
<br />
The % and %! character sequences can also be used as part of a 1.2.1+ non-branching conditional to continue or break the loop:<br />
<br />
<pre><br />
--?"X[&RollInto]X" -eq "XX"|%<br />
</pre><br />
<br />
In this example, if the string variable RollInfo is empty, the loop will return to the top and continue with the next iteration, while:<br />
<br />
<pre><br />
--?"X[&RollInto]X" -eq "XX"|%!<br />
</pre><br />
<br />
Would cause the whole loop to end if the condition were true.<br />
<br />
== Referencing ==<br />
<br />
=== Roll Variables===<br />
<br />
Roll Variables can be referenced from the content portion of any line type, and from the tag portion of conditional statements. The referenced value is replaced when the line is executed.<br />
<br />
There are several modifiers that can be used to reference parts of a roll:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Modifier !! Meaning<br />
|-<br />
| No modifier || In a Direct Output Line (<nowiki>--+</nowiki>), GM Output Line (<nowiki>--*</nowiki>), or String Assignement (<nowiki>--&</nowiki>), 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<br />
|-<br />
| .Total || The end result of the roll equation. Formatting rules for "No Modifier" apply based on line type. <br />
|-<br />
| .Raw || The total value of the roll variable without any formatting, no matter what kind of line the reference is used in.<br />
|-<br />
| .Base || The cumulative result of any dice rolled in the Roll Text (Numeric modifiers are not included) <br />
|-<br />
| .Ones || The number of dice in the roll that came up as 1s <br />
|-<br />
| .Aces || The number of dice in the roll that came up as the maximum number on the die <br />
|-<br />
| .Odds || The number of dice in the roll that came up with an odd number <br />
|-<br />
| .Evens || The number of dice in the roll that came up with an even number <br />
|-<br />
| .RollText || The raw text of the roll that was use to generate the results <br />
|-<br />
| .Text || A text representation of the results of the roll, including the numbers rolled for each die <br />
|-<br />
| .tableEntryText || The text portion of the result of a table roll<br />
|-<br />
| .tableEntryImgURL || The image source portion of the result of a table roll<br />
|-<br />
| .tableEntryValue || If the tableEntryText is purely numeric, will contain the numeric value<br />
|}<br />
<br />
=== String Variables ===<br />
<br />
To reference a string variable, use the notation [&variablename]. String variables can be referenced in direct output, roll variable assignment, and string variable assignment statements.<br />
<br />
=== Character/Token Attributes ===<br />
<br />
A character or token attribute can be referenced from content portion of any type of line and is substituted when the line is executed. The general format for referencing a character attribute is [*ID:attribute]. ID can be a token ID or a character ID (these start with a dash). Additionally if you have specified a sourceToken or targetToken, you can substitute "S" or "T" for the ID (for example [*S:npc_type] will retrieve the npc_type attribute from the source token.<br />
<br />
By default, all attribute references will be pulled from the '''''character''''' object that the ID represents (either directly or by being a Token ID that represents a character).<br />
<br />
Keep in mind, that if you want to access the "max" of a character attribute (for example, the max hit points), then you cannot trust the name that your roll20 character sheet shows you when you hover your mouse over the max hit points. For example, this reference will not work: [*S:hp_max]. Instead, you need to use this reference: [*S:hp^].<br />
<br />
If your ID refers to a token, token attributes can be accessed by preceding the attribute name with "t-", for example [*S:t-aura1_radius]. Supported token attributes are:<br />
<br />
{|<br />
| t-name || t-id || t-statusmarkers || t-bar1_value<br />
|-<br />
| t-bar1_max || t-bar2_value || t-bar2_max || t-bar3_value<br />
|-<br />
| t-bar3_max || t-top || t-left || t-width<br />
|-<br />
| t-height || t-rotation || t-layer || t-aura1_radius<br />
|-<br />
| t-aura1_color || t-aura2_radius || t-aura2_color || t-aura1_square<br />
|-<br />
| t-aura2_square || t-tint_color || t-light_radius || t-light_dimradius<br />
|-<br />
| t-light_angle || t-light_losangle || t-light_multiplier || t-light_otherplayers<br />
|-<br />
| t-light_hassight || t-flipv || t-fliph || t-controlledby<br />
|-<br />
| t-_cardid || t-_pageid || t-imgsrc || t-bar1_link<br />
|-<br />
| t-bar2_link || t-bar3_link || t-represents || t-layer<br />
|-<br />
| t-isdrawing || t-name || t-gmnotes || t-showname<br />
|-<br />
| t-showplayers_name || t-showplayers_bar1 || t-showplayers_bar2 || t-showplayers_bar3<br />
|-<br />
| t-showplayers_aura1 || t-showplayers_aura2 || t-playersedit_name || t-playersedit_bar1<br />
|-<br />
| t-playersedit_bar2 || t-playersedit_bar3 || t-playersedit_aura1 || t-playersedit_aura2<br />
|-<br />
| t-lastmove || t-adv_fow_view_distance || t-has_bright_light_vision || t-has_night_vision<br />
|-<br />
| t-night_vision_distance || t-emits_bright_light || t-bright_light_distance || t-emits_low_light<br />
|-<br />
| t-low_light_distance || t-has_limit_field_of_vision || t-limit_field_of_vision_center || t-limit_field_of_vision_total<br />
|-<br />
| t-has_limit_field_of_night_vision || t-limit_field_of_night_vision_center || t-limit_field_of_night_vision_total || t-has_directional_bright_light<br />
|-<br />
| t-directional_bright_light_center || t-directional_bright_light_total || t-has_directional_dim_light || t-directional_dim_light_center<br />
|-<br />
| t-directional_dim_light_total || t-lightColor || || |<br />
|}<br />
<br />
'''''It is important to note that some attributes names on tokens have corresponding attribute names on characters, which represent different values. For example, [*T:id] returns the character ID, while [*T:t-id] returns the token ID.'''''<br />
<br />
=== Subroutine Parameters ===<br />
<br />
When using a gosub statement (-->) or a conditional marked as a gosub (prefixing the label with a > character), you can pass any number of parameters separated by semicolons (;) that the code in the subroutine can utilize.<br />
<br />
Subroutine parameters are numbered starting at 1, and are accessed by using the notation [%number%], so the first parameter is [%1%], the second is [%2%], etc.<br />
<br />
Parameter substitution happens on all line types, and happens prior to character attribute references or roll variable substitution.<br />
<br />
=== Campaign Attribute ===<br />
You can retrieve properties of the API's Campaign object with the [*C:attributename] syntax. For example, [*C:playerpageid] will retrieve the current player ribbon page from the Campaign object.<br />
<br />
=== Page Attributes ===<br />
If you have set the '''activepage''' parameter, you can retrieve page-related properties with the [*P:attributename] syntax, including the page's UDL parameters.<br />
<br />
=== Repeating Section Values ===<br />
<br />
You can reference repeating attribute data using the syntax [*R:attributename] syntax (similar to referencing standard character attributes). The currently active repeating row information will be used to retrieve attribute values. You can also retrieve the full attribute name for a repeating row attribute by using the [*R>attributename] notation. This is useful to pass to things like chatsetattr.<br />
<br />
=== Array Elements ===<br />
After an array has been declared, the elements can be referenced with [@arrayName(index)]. Array indices start at 0.<br />
<br />
== Deferred Resolution for Meta Scripts ==<br />
<br />
As of 1.2.9, ScriptCards supports a deferral character for use when calling another API script with via the --@ statement, to defer processing of meta script references so they get processed prior to the sub-API call insted of prior to ScriptCards execution. To defer this processing for meta script (SelectManager, Fetch) by inserting a deferral character into the meta call. For example, if I want to have ScriptCards call TokenMod as if the token for "Quej Gr'stra" (yes, I let Roll20 name my test NPCs) I could use something like this:<br />
<br />
--@token-mod|{^& select Quej Gr'stra} _on showname<br />
<br />
The "^" in between { and & will prevent SelectManager from seeing the call when the ScriptCard script is processed, but the --@ statement will remove the deferral character so the command that will be sent by ScriptCards is:<br />
<br />
!token-mod {& select Quej Gr'stra} --on showname<br />
<br />
With the deferral character removed, SelectManager will see the {& select ...} and do its magic.<br />
<br />
While the default deferral character is "^", the deferral character is a setting that can be changed:<br />
<br />
--#deferralcharacter|%<br />
<br />
Will make % the deferral character for future --@ statements in the running script.<br />
<br />
There are currently three supported Meta script structures: {^&...} for SelectManager, @^(...) and *^(...) for fetch, where the ^ in the structures here represents the placement of the deferral character.<br />
<br />
== Arrays ==<br />
<br />
Arrays are a new data type introduced in version 1.1.12 of ScriptCards, and are manipulated with associated function (--~) commands.<br />
<br />
* Arrays are a lists of strings. Items in an array cannot contain the semi-colon (;) character, as that is used to separate parameters in the function code that deals with arrays.<br />
* Arrays are accessed via the --~ script command. In some cases, the value of the tag (variable name) for array commands is not used, and can be a dummy value or simply omitted. I have omitted them in the statements below.<br />
* All commands that DO return a value return string values, even if the content is numeric.<br />
* If a command returns a value and there is some sort of reason that it isn't an array value, you will get "ArrayError" in the return value. This can happen if you reach the end of an array while stepping through it, for example, so checking for "ArrayError" can serve as the end condition for a loop.<br />
* Each array keeps track of its current index, allowing you to step forward and backwards through arrays.<br />
* Any number of arrays can be defined.<br />
* Unlike string variables and roll variables, array variables cannot (currently) be referenced directly. It is necessary to use the function (--~) syntax to manipulate arrays and get values from them as strings for use in other parts of your script.<br />
<br />
<br />
== Reentrant Scripts ==<br />
<br />
Reentrant scripts allow you to create buttons in your script code that will re-execute the script at a given label within the code. If you set the reentrant setting (--#reentrant|somevalue) to a non-zero value, your setting and variable information will be preserved between executions. Reentrant script can be used to present menus or choices and then continue acting.<br />
<br />
Reentrant buttons are created with the [rbutton]Caption::ReentryLabel;Parameter[/rbutton] construct. The caption will be displayed on the generated button. ReentryLabel is the name of a label in your script that the button will jump to when clicked, and Parameter will be passed in as a string value called "reentryval".<br />
<br />
Example:<br />
<pre><br />
!script {{<br />
--#reentrant|testing<br />
--=Roll|1d20<br />
--+Roll|[$Roll]<br />
--&String|That was a [$Roll.Raw]!<br />
--~x|array;define;MyArray;Apple;Banana;Orange<br />
--+Try it|[rbutton]Hello!::EXEC_PC_SPELL;9[/rbutton]<br />
--X|<br />
<br />
--:EXEC_PC_SPELL|<br />
--+ReentryVal|[&reentryval]<br />
--+The value of Roll is|[$Roll]<br />
--+Value of String|[&String]<br />
--+Array|[@MyArray(0)]<br />
--X|<br />
}}<br />
</pre><br />
<br />
This script sets up some variables and then displays a button labeled "Hello!". If the user clicks the button, the script will be re-entered starting at the "EXEC_PC_SPELL", which will display the content of the variables from the original execution.<br />
<br />
'''''Note: This section needs to be expanded upon'''''<br />
<br />
== Procedure Libraries ==<br />
<br />
You can now create handouts in your game in Roll 20 with the name format "ScriptCards Library NAME", where name is a name you assign to the library. Library names are case sensitive. It is my hope that the more proficient ScriptCards scripters out there will provide procedure libraries (or procedures that can be included in libraries) for others to use to make their scripting life easier. Be they specific to a game system, or to a type of activity, I think a robust set of libraries that GMs could use to enhance their scripting capabilities would be very valuable to the community. Should such things begin to emerge, I’ll create a portion of the ScriptCards Wiki page to house them.<br />
<br />
To include one or more libraries in a script, use the +++libname+++ directive (does not need a -- line associated with it). Multiple library names can be specified by separating them with semicolons (i.e., +++General;dnd5elib;Colorize+++ would include three libraries (General, dnd5elib, and Colorize).<br />
<br />
Included libraries are separated from the main script code by the automatic inclusion of "--X|" before the first library is appended to the script, and all libraries are loaded at the end of the script before script processing takes place.<br />
<br />
Procedures and labels in libraries can be used just as if they were included in the body of your script. Note that this DOES mean that you could, technically, jump into a library with a direct branch (--^) or direct branch conditional, but I recommend using libraries to store reusable procedures.<br />
The Notes section of the library handout stores the library code, and is written just like any other ScriptCards code except:<br />
<br />
* They cannot use roll queries (?{Some Prompt:}) to get information from the user at execution time.<br />
* They cannot use @{} notation to access character and token information.<br />
<br />
Both of these limitation stem from the fact that Procedure Libraries are not processed by the chat server, which is what handles these items.<br />
<br />
Here is an example of handling damage modifications (resistance, vulnerability, and immunity) in D&D 5E with a library:<br />
<br />
<pre><br />
!script {{<br />
+++dnd5elib+++<br />
--#|Damage Modifiers Test<br />
--#targettoken|@{target|token_id}<br />
-->Lib5E_CheckDamageModifiers|ResistType;fire<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] fire damage<br />
<br />
-->Lib5E_CheckDamageModifiers|ResistType;cold<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] cold damage<br />
<br />
-->Lib5E_CheckDamageModifiers|ResistType;poison<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] poison damage<br />
<br />
-->Lib5E_CheckDamageModifiers|ResistType;acid<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] acid damage<br />
<br />
--X|<br />
}}<br />
</pre><br />
<br />
Library content (In a handout called “ScriptCards Library dnd5elib” NOTE: Paste into Notepad first and then paste into the handout in Roll20 to avoid bringing over HTML formatting from the web site):<br />
<br />
<pre><br />
--/|ScriptCards Library: dnd5elib version 0.0.1<br />
--/|Provides various utility procedures for D&D 5E games<br />
<br />
--/|Lib5E_CheckDamageModifiers handle damage resistance, vulnerability, and immunity. <br />
--/|Pass a string variable to be filled with a string to be appended to a dice roll and the damage type <br />
<br />
--:Lib5E_CheckDamageModifiers|damageVariableName;damageType<br />
--&[%1%]|<br />
--?"[*T:npc_vulnerabilities]" -inc "[%2%]"|>_Lib5E_IsVulnerable;[%1%]<br />
--?"[*T:npc_resistances]" -inc "[%2%]"|>_Lib5E_IsResistant;[%1%]<br />
--?"[*T:npc_immunities]" -inc "[%2%]"|>_Lib5E_IsImmune;[%1%]<br />
--<|<br />
<br />
--:_Lib5E_IsVulnerable| --&[%1%]| * 2 [Vulnerable] --<|<br />
--:_Lib5E_IsResistant| --&[%1%]| \ 2 [Resistant] --<|<br />
--:_Lib5E_IsImmune| --&[%1%]| * 0 [Immune] --<|<br />
</pre><br />
<br />
The idea is that the functions in the library create a string that can be appended to a roll to modify the output based on resistances, so you pass Lib5E_CheckDamageModifiers the name of the string variable you want to use and the damage type. The variable (ResistType in this case) will include either nothing, “* 2 [Vulnerable]”, “\ 2 [Resistant]”, or “* 0 [Immune]” which can be included in a roll assignment (--=) to modify the damage as appropriate. The order here might be important if an NPC is misconfigured to be both resistant and immune to the same damage type. Since immune is an absolute, having it last ensures that it will override resistant or vulnerable. A creature that is both vulnerable and resistant (again, misconfigured) will come back as resistant since that condition is checked after vulnerable.<br />
Some notes: I prefix my library labels with either “Lib5E_” or “_Lib5E_” as a clarity convention. This isn’t strictly necessary but you should be aware that if two libraries (or if your script and a library) define the same label, the last label defined will win. Since libraries are appended to the end of the script in the order you include them in the +++libname+++ directive, you can somewhat control this, but it is probably best to avoid re-declaring labels. <br />
<br />
In my case, items beginning with “Lib5E_” are intended to be called by scripts, while items beginning with “_Lib5E_” are intended to be used as subroutines by the “public” procedures. Of course, there is no reason you couldn’t call them directly.<br />
<br />
You might also note that I’ve included some library information in comment lines (--/|) at the top of the library. These are ignored by ScriptCards, and are a good way to convey requirements, parameters, usage information, etc.<br />
<br />
== Example Libraries ==<br />
<br />
=== dnd5elib ===<br />
<br />
[https://github.com/kjaegers/ScriptCards Download the dnd5elib Library from the ScriptCards GitHub]<br />
<br />
The '''dnd5elib''' library provides a collection of utility procedures that help simplify dealing with the D&D 5E Official Sheet. Some of the procedures in this library require '''chatsetattr''' to be installed in your game. This is a growing library, and currently only has a handful of routines. They are:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Procedure Name !! Notes<br />
|-<br />
| style="white-space:nowrap" | Lib5E_CheckDamageModifiers || This procedure can be used to evaluate vulnerabilities, resistances, and invulnerabilities on an NPC. After setting the --#target| parameters, pass the Lib5E_CheckDamageModifiers procedure a variable name (no reference information) and a damage type (i.e., fire, cold, bludgeoning, etc.) and a string variable with the name passed in as the first parameter will be created that contains text that can be included in a roll line (--=) in order to modify the roll as appropriate. For example, '''-->Lib5E_CheckDamageModifiers|ResistType;fire''' will check the current target character's attributes for "fire" and will either return an empty string (no references), "* 0 [Immune]" if the creature is immune, "\ 2 [Resistant]" if the creature is resistant, or "* 2 [Vulnerable]" if the creature is vulnerable to fire damage.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_DeductSpellSlot || Pass in a character_id and a slot level, and the script will expend one spell slot of that level, capping the value at 0 slots remaining. For Example '''<nowiki>-->Lib5E_DeductSpellSlot|@{selected|character_id};1</nowiki>''' to deduct a first level spell slot from the selected character.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_FindResource || Used to locate a resource value on a character. Pass in a character_id, a resource name, and two variable names. The procedure will check both repeating and non-repeating resources looking for a resource whose name matches what was passed in and return three variables. The first will be a string variable named for the 3rd parameter and contains the attribute name of the resource's "name" field. The second will be a string variable named after parameter 4 and contains the resource's value field attribute name, and the third variable is a Roll Variable, also named after the 4th parameter that contains the current resource value. Example: '''<nowiki>-->Lib5E_FindResource|@{selected|character_id};Crossbow bolts;ResName;ResValue</nowiki>''' will find "Crossbow bolts" as a resource on the character and return [&ResName] which is the name of the resource attribute, [&ResValue] which is the '''name of the attribute that stores the value''' and [$ResValue] which is the current numeric value of the resource.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Global_Attack_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Attack Modifiers (repeating_tohitmod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Bless" for 1d4 active and "Being Cool" for +2 active, I will get a return string " + 1d4 [Bless] + 2 [Being Cool]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Save_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Save Modifiers (repeating_savemod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Bless" for 1d4 active and "Being Cool" for +2 active, I will get a return string " + 1d4 [Bless] + 2 [Being Cool]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Skill_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Skill Modifiers (repeating_skillmod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Guidance" for 1d4 active and "Being Cool" for +2 active, I will get a return string " + 1d4 [Guidance] + 2 [Being Cool]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_AC_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Save Modifiers (repeating_savemod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Shield of Faith" with a value of 2 active, I will get a return string " + 2 [Shield of Faith]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Damage_Modifiers || Pass a character ID and TWO string variable to set the return value. The first string will be for normal damage, and the second will be the additional damage on a crit. This procedure will look through the Global Damage Modifiers (repeating_damagemod_*) for rows that are active (checked on the character sheet) and return two strings with the dice rolls and descriptions for them (for example, if I have "Sneak Attack" with a value of 1d6 normal and 1d6 critical damage active, I will get a return string " + 1d6 [Sneak Attack]" and another string of " + 1d6 [Sneak Attack CRIT]" that can be used in a dice rolls.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_DivineSmiteDice || Used to calculate the number of dice to be rolled for a paladin's Divine Smite. Pass a target token id, a spell slot level, and a string variable to be set to the dice roll amount based on the NPC_TYPE attribute of the target token. The returned variable will contain a dice roll (like "3d8" that can be used in a --= line)<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Character_Summary || Pass a character ID to outputs a mini character sheet, including clickable buttons for attacks, actions, legendary actions, etc. Will automatically detect a PC vs NPC and output the appropriate sections.<br />
|}<br />
<br />
Due to formatting issues with the Wiki, the library code has been moved to a [https://gist.github.com/kjaegers/52f6049ddd257f0a1288aca4bbde13c5 GITHUB GIT]. Please view the GIST in raw mode and copy the text and paste it into a handout called "ScriptCards Library dnd5elib" in your Roll20 Game.<br />
<br />
== What to Know if you are Coming from PowerCards ==<br />
<br />
''Note: This section is a work in progress.''<br />
<br />
While ScriptCards and PowerCard have very similar output goals, their internals and use are quite different. The table below summarizes some of the major differences between the scripts.<br />
<br />
::{| class="wikitable"<br />
|-<br />
! PowerCards !! ScriptCards <br />
|-<br />
| With a handful of exceptions, all lines in a PowerCard macro are intended to produce a line of output on the final card. || With ScriptCards, ONLY the <code>--+</code> and <code>--*</code> statement types produces output <br />
|-<br />
| PowerCards lines begin with two dashes (<code>--</code>) followed by a unique tag name for the line, followed by a vertical bar and the content for the line. || ScriptCards lines begin with two dashes (<code>--</code>) followed by a '''statement type identifier''', which is a single character that identifies the type of line to the interpreter. This is followed by a tag (frequently optional), a vertical bar, and the parameters for the statement being executed.<br />
|-<br />
| PowerCard macros are always processed top to bottom. Lines can be hidden so they don't output anything, but there is no looping or branching (--SkipTo looks like a branch, but it just hides all of the lines until the referenced label. || ScriptCards scripts support true branching, including direct branching (<code>--^</code>) and procedure branching (<code>--></code>) and (<code>--<</code>). Procedures support parameters and a call stack so procedures can be nested to call other procedures.<br />
|-<br />
| All lines in a PowerCards macro need to have unique tags because PowerCards builds the card as a single JavaScript object using the tag names to store what will be displayed. This is why repeated tag names always result in the last one being shown. || ScriptCards tags do not need to be unique, and in the case of many line types are optional.<br />
|-<br />
| PowerCards conditionals result in either showing or hiding the line they are on. || ScriptCards conditionals '''''only''''' support branching as the result of the comparison. This branching can be direct (a GOTO) or procedural (a GOSUB) '''''NOTE: As of version 1.2.0, ScriptCards also supports roll/string variable assignment as a result of conditional evaluation'''''<br />
|-<br />
| PowerCards relies on the Roll20 [[Quantum Roll]] server and inline rolls for all dice functions || ScriptCards includes its own dice roll parser, and '''''does not support''''' inline rolls.<br />
|-<br />
| PowerCards RollIDs (often mistaken for variables) are assigned by analyzing the results of an inline roll, and cannot be referenced in other rolls, so you can't roll a <code>1d4</code> and then roll a <code>1d20</code> and add the <code>1d4</code> result because all of the rolls happen on the chat server before PowerCards gets the macro text. || ScriptCards supports two types of variables: Roll Variables and String Variables. Because ScriptCards uses its own roll parser and is not dependent upon the chat server, rolls and their results can be used in other rolls, math functions, output, etc.<br />
|}<br />
<br />
== Example Scripts ==<br />
<br />
Below are some sample scripts that utilize the various statement types in ScriptCards:<br />
<br />
=== Divine Smite ===<br />
<br />
This script will prompt the user for a spell slot level to expend on a divine smite. It will check the target's npc_type to see if it is an Undead or Fiend, which adds an additional d8 to the smite roll.<br />
<br />
[[File:ScriptCards Divine Smite.png|Divine Smite Script Output]]<br />
<br />
<pre><br />
!scriptcard {{<br />
--#title|Divine Smite<br />
--=DiceCount|?{Spell Slot Level?|1|2|3|4|5|6|7|8|9} + 1<br />
--=IsFiendOrUndead|0<br />
--?"@{target|npc_type}" -inc fiend|>IsBoosted<br />
--?"@{target|npc_type}" -inc undead|>IsBoosted<br />
--=TotalDice|[$DiceCount] + [$IsFiendOrUndead]<br />
--=SmiteRoll|[$TotalDice]d8<br />
--#emoteText|@{selected|token_name} smites @{target|token_name}<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
--+Smite|deals [$SmiteRoll] radiant damage.<br />
--X|<br />
<br />
--:IsBoosted|<br />
--=IsFiendOrUndead|1<br />
--<|<br />
}}<br />
</pre><br />
<br />
==== How It Works ====<br />
<br />
The first line sets the "title" card parameter to "Divine Smite".<br />
<br />
Line 2 Shows a query to the user asking for the spell slot level, adds one and stores the value in the "DiceCount" Roll Variable. The query/dropdown is generated by the chat server prior to the script being executed.<br />
<br />
Line 3 defaults the "IsFiendOrUndead" Roll Variable to 0.<br />
<br />
Lines 4 and 5 compare the target's "npc_type" attribute (passed by the chat server as text) to see if they include either "undead" or "fiend". If true, the IsBoosted subroutine will be called. No parameters are passed to this subroutine.<br />
<br />
Line 6 sets the "TotalDice" variable to the base (DiceCount) number plus the IsFiendOrUndead number, which will be a 0 or a 1.<br />
<br />
Line 7 calculates "SmiteRoll" by rolling a number of d8 equal to the "TotalDice" value.<br />
<br />
Lines 8-10 set the parameters for the emote, which appears above the card content. By setting the sourceToken and the targetToken, their icons will appear in the emote surrounding the text describing the action.<br />
<br />
Line 11 is the only line that actually produces output on the card. It results in "Smite deals # radiant damage".<br />
<br />
Line 12 ends the script execution, preventing the script from continuing and running the subroutines out of context.<br />
<br />
Lines 14-16 are the IsBoosted subroutine, starting with the :IsBoosted label. The IsFiendOrUndead variable is set to 1, and a return from subroutine is executed.<br />
<br />
=== Magic Missile ===<br />
<br />
This script demonstrates using a loop and calling a subroutine to fire a number of missiles determine by the spell slot level used to cast the spell.<br />
<br />
[[File:ScriptCards_MagicMissile_Fixed.png|Magic Missile Script Output]]<br />
<br />
<pre><br />
!scriptcard {{ <br />
--#title|Magic Missile<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
--=MissileCount|?{Spell Slot Level?|1|2|3|4|5|6|7|8|9} + 2<br />
--=DisplayCount|1<br />
--=MissileDamage|0<br />
--#leftsub|Slot level ?{Spell Slot Level?}<br />
--#rightsub|Ranged Attack<br />
--#emoteText|Fred uses a level ?{Spell Slot Level?} spell slot to fire [$MissileCount.Total] missiles of magical force!<br />
--:MissileLoop|<br />
-->FireMissile|<br />
--=DisplayCount|[$DisplayCount] + 1<br />
--?[$DisplayCount] -le [$MissileCount]|MissileLoop<br />
--+Total|Total damage is [$MissileDamage]<br />
--X|<br />
<br />
--:FireMissile|<br />
--=ThisMissile|1d4 + 1<br />
--=MissileDamage|[$MissileDamage] + [$ThisMissile]<br />
--+Missile|[$DisplayCount.Total] Hits for [$ThisMissile] [b]force[/b] damage<br />
--<|<br />
}}<br />
</pre><br />
<br />
==== How It Works ====<br />
<br />
Lines 1-3 set the card title, the source token and the target token. Setting these tokens causes their icons/avatars to appear in the Emote section of the card.<br />
<br />
Line 4 asks the user what spell slot level they wish to use to cast magic missile. The number of missiles fired is equal to 2 plus the spell level, and this is stored in the MissileCount variable.<br />
<br />
Line 5 stores a 1 in the DisplayCount variable. This will be used to control the loop to determine the number of missiles fired and the missile number when displaying damage rolls.<br />
<br />
Line 6 initializes MissileDamage to 0<br />
<br />
Line 7 sets the left subtitle to the text "Slot Level #", where # is the spell slot level being used.<br />
<br />
Line 8 sets the right subtitle to the text "Ranged Attack".<br />
<br />
Line 9 sets the emoteText parameter with a description of the action, including the slot level and number of missiles fired.<br />
<br />
Line 10 is a label for the missile firing loop<br />
<br />
Line 11 Calls the "FireMissile" subroutine<br />
<br />
Line 12 increases the DisplayCount variable by 1<br />
<br />
Line 13 Checks to see if there are still missles to fire (DisplayCount <= MissileCount) and if so branches to MissileLoop<br />
<br />
Line 14 Displays the total damage dealt by the spell.<br />
<br />
Line 15 stops execution of the script to prevent out of context execution of the subroutine.<br />
<br />
Lines 76-21 are the FireMissile subroutine, beginning with the FireMissile label. The 1d4+1 is rolled and assigned to "ThisMissile". The result is added to the existing MissileDamage total, and a line for the current missile is displayed with the missile number and the damage for the missile.<br />
<br />
=== Longsword Attack ===<br />
<br />
This script demonstrates a standard 5E D&D melee weapon attack, including detection of misses, fumbles, hits, and critical hits. If installed, alterbars is used to decrement the target's BAR3 value by the damage dealt.<br />
<br />
[[File:ScriptCards Longsword.png|Longsword Script Output]]<br />
<br />
<pre><br />
!scriptcard {{<br />
--#title|Longsword<br />
--#leftsub|Melee Attack<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
--#emoteText|@{selected|token_name} attacks @{target|token_name}<br />
--=TargetAC|@{target|npc_ac}<br />
--?[$TargetAC.Total] -gt 0|DoneWithAC<br />
--=TargetAC|@{target|ac}<br />
--:DoneWithAC|<br />
--=AttackRoll|1d20 + @{selected|strength_mod} [STR] + @{selected|pb} [PROF]<br />
--+Attack|@{selected|token_name} rolls [$AttackRoll] vs AC [$TargetAC].<br />
--?[$AttackRoll.Base] -eq 20|Crit<br />
--?[$AttackRoll.Base] -eq 1|Fumble<br />
--?[$AttackRoll.Total] -ge [$TargetAC.Total]|Hit<br />
--+Miss|The attack missed.<br />
--^Final|<br />
<br />
--:Fumble|<br />
--+Fumble!|The attack went horribly wrong.<br />
--^Final|<br />
<br />
--:Hit|<br />
--=Damage|1d8 + @{selected|strength_mod} [STR]<br />
--+Hit!|The attack hit @{target|token_name} for [$Damage] slashing damage.<br />
--@alter|_target|@{target|token_id} _bar|3 _amount|-[$Damage]<br />
--^Final|<br />
<br />
--:Crit|<br />
--=Damage|1d8 + @{selected|strength_mod} [STR] + 1d8 [CRIT]<br />
--+Critical Hit!|The attack hit @{target|token_name} for [$Damage] slashing damage.<br />
--@alter|_target|@{target|token_id} _bar|3 _amount|-[$Damage]<br />
<br />
--:Final|<br />
}}<br />
</pre><br />
<br />
==== How it Works ====<br />
<br />
In lines 1-5, we set the title, subtitle, and emote text along with the tokens for the emote area.<br />
<br />
Lines 6-9 allow us to determine the AC of the target. On the 5E Roll20 sheet, NPCs armor class is stored in "npc_ac", while PCs armor class is in "ac". First we grab npc_ac and if it is zero, we check AC.<br />
<br />
Line 10 rolls the attack roll, rolling 1d20 and adding the attacker's strength modifier and proficiency bonus<br />
<br />
Line 11 displays the result of the attack roll on the card<br />
<br />
Lines 12-14 determine what kind of result the attack had. If the .Base value of the roll was 20, we branch to "Crit". If it was 1, we branch to "Fumble". If the .Total value of the roll was greater than or equal to the AC that was determined in Lines 6-9, we branch to Hit.<br />
<br />
Assuming we didn't branc anywhere, the result of the attack was a miss, so we display that on line 15 and then branch to "Final"<br />
<br />
This is followed by three branch segments, :Fumble, :Hit, and :Crit. A fumble displays a text message and branches to :Final.<br />
<br />
On a hit or a crit, we roll Damage (adding additional damage dice on a crit). We display a "Hit!" or "Critical Hit!" message and then make an API call to AlterBars, passing it the token id, bar we want to modify (3 in this case), and the amount we want to modify by the Damage value.<br />
<br />
=== Party Health Status ===<br />
<br />
This example calculates the current Hit Points remaining and HP percentage for each character and creates a color-coded display with the current party status.<br />
<br />
[[File:ScriptCards Party Health.png]]<br />
<br />
<pre><br />
!scriptcard {{<br />
--#title|Party Status<br />
--#titleCardBackground|#33CC33<br />
--#oddrowbackground|#bfee90<br />
--#evenrowbackground|#90eebf<br />
-->HealthCheck|@{Quej Grastra|character_id}<br />
-->HealthCheck|@{Brim Cheuto|character_id}<br />
-->HealthCheck|@{Odug Ututees|character_id}<br />
--X|End of card Execution<br />
<br />
--:HealthCheck|<br />
--=HealthPerc|[*[%1%]:hp] / [*[%1%]:hp^] * 100 \ 1<br />
--=HealthColor|000000<br />
--?[$HealthPerc.Total] -gt 50|HealthSkip<br />
--=HealthColor|FF0000<br />
--:HealthSkip|<br />
--+[*[%1%]:character_name]|has [#[$HealthColor.RollText]][*[%1%]:hp] of [*[%1%]:hp^][/#] HP [R]([$HealthPerc.Total]%)[/R]<br />
--<|End of HealthCheck<br />
}}<br />
</pre><br />
<br />
==== How it Works ====<br />
<br />
Lines 1-4, we set the card title, and set the title background and row background colors to shades of green.<br />
<br />
Lines 5-7 make gosub calls the the "HealthCheck" subroutine, passing in the character ID of each of the named characters (these are the names of the characters in my test game)<br />
<br />
Line 8 terminates the script execution.<br />
<br />
The remaining lines of the script are the HealthCheck subroutine, which works like this:<br />
<br />
Line 10 is the subroutine label (:HealthCheck)<br />
<br />
Line 11 uses the character id passed as a parameter and combines it with character attribute lookup *(...) to retrieve the value of "hp" and "hp<nowiki>^</nowiki>" for the character. The <nowiki>^</nowiki> character is used to specify that we want the MAX value for this attribute for the second call. We divide these two numbers and multiple by 100 to get a percentage. Finally, we use integer division by 1 to round the percentage and drop the decimals. The end result gets stored in the HealthPerc roll variable.<br />
<br />
Line 12 defaults to color of the health text to black<br />
<br />
Line 13 check to see if the health percentage is greater than 50. If so, it branches to HealthSkip, preventing the script from executing line 13.<br />
<br />
Line 14 sets the color of the health text to red<br />
<br />
Line 15 is the label that will be branched to from Line 13 to skip the red coloring<br />
<br />
Line 16 again uses character attribute substitution and the passed parameter value to output a display line containing the character name, the colorized health total, and the percentage value. The percentage is right-justified.<br />
<br />
Line 17 returns from the HealthCheck subroutine.<br />
<br />
=== Expanded Magic Missile Script ===<br />
<br />
This is the expanded and enhanced version of the Magic Missile script covered in {{yt|watch?v=u50xvNzS9Zk | this video}}. It includes visual and audio effects, checking and deducting spell slots, and applying damage using either Token-Mod or Alterbars.<br />
<br />
<pre><br />
!scriptcard {{ <br />
--#title|Magic Missile<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
<br />
-->GetAndCheckSlotInformation|<br />
<br />
--=MissileCount|[$SlotLevel] + 2<br />
--=DisplayCount|1<br />
--=MissileDamage|0<br />
--#leftsub|Slot level [$SlotLevel]<br />
--#rightsub|Ranged Attack<br />
--#emoteText|@{selected|character_name} uses a level [$SlotLevel.Total] spell slot to fire [$MissileCount.Total] missiles of magical force!<br />
<br />
--:MissileLoop|<br />
-->FireMissile|<br />
--=DisplayCount|[$DisplayCount] + 1<br />
--?[$DisplayCount] -le [$MissileCount]|MissileLoop<br />
--+Total|Total damage is [$MissileDamage]<br />
-->DeductSpellSlot|<br />
--#rightsub|Level [$SlotLevel] Left: [$SlotsRemaining] <br />
-->PlayEffects|none;burst-smoke;beam-magic;spell_01<br />
-->ApplyDamageTokenmod|@{target|token_id};3;-[$MissileDamage]<br />
-->ApplyDamageAlterbars|@{target|token_id};3;-[$MissileDamage]<br />
--X|<br />
<br />
--:FireMissile|<br />
--=ThisMissile|1d4 + 1<br />
--=MissileDamage|[$MissileDamage] + [$ThisMissile]<br />
--+Missile|[$DisplayCount.Total] Hits for [$ThisMissile] [b]force[/b] damage<br />
--<|<br />
<br />
--:GetAndCheckSlotInformation|<br />
--=SlotLevel|?{Spell Slot Level?|1|2|3|4|5|6|7|8|9}<br />
--=SlotsTotal|[*S:lvl[$SlotLevel]_slots_total]<br />
--=SlotsExpended|[*S:lvl[$SlotLevel]_slots_expended]<br />
--?[$SlotsExpended.Total] -ge [$SlotsTotal.Total]|NoSlotsLeft<br />
--<|<br />
<br />
--:NoSlotsLeft|<br />
--+|[*S:character_name] has no level [$SlotLevel.Total] spell slots available.<br />
--X|<br />
<br />
--:DeductSpellSlot|<br />
--=SlotsExpended|[$SlotsExpended] + 1<br />
--@setattr|_charid [*S:character_id] _lvl[$SlotLevel]_slots_expended|[$SlotsExpended] _silent<br />
--=SlotsRemaining|[$SlotsTotal] - [$SlotsExpended]<br />
--<|<br />
<br />
--:PlayEffects|Parameters are : source effect; target effect; line effect; sound effect<br />
--vtoken|@{selected|token_id} [%1%]<br />
--vtoken|@{target|token_id} [%2%]<br />
--vbetweentokens|@{selected|token_id} @{target|token_id} [%3%]<br />
--@roll20AM|_audio,play,nomenu|[%4%]<br />
--<|<br />
<br />
--:ApplyDamageTokenmod|Parameters are tokenid;bar#;amount<br />
--@token-mod|_ignore-selected _ids [%1%] _set bar[%2%]_value|[%3%]<br />
--<|<br />
<br />
--:ApplyDamageAlterbars|<br />
--@alter|_target|[%1%] _bar|[%2%] _amount|[%3%]<br />
--<|<br />
}}<br />
</pre><br />
<br />
[[Category:Featured articles]]</div>5004103https://wiki.roll20.net/Script:ScriptCardsScript:ScriptCards2021-09-28T18:02:25Z<p>5004103: /* Comment (--/) */</p>
<hr />
<div>{{revdate}}<br />
== Introduction ==<br />
'''ScriptCards''' provides a script interpreter that can be used to create powerful macros that display the results of player/NPC actions, or display other information in a pleasing visual format in your game's chat window. The scripting language contains variables (both dice-roll (enhanced numerics) and strings) as well, conditionals, branching, subroutines with parameters, and a set of built-in functions to simplify working with Roll20 information.<br />
{{script overview<br />
|name=ScriptCards<br />
|author={{user profile|2365448|Kurt J.}}<br />
|code=<br />
|version=1.4.0e<br />
|lastmodified=2021-09-24}}<br />
ScriptCards is not game-system specific, and can be used with any system/sheet. Near the end of this Wiki there is a section set aside for libraries that can implement system-specific tasks, with the hope that enthusiasts playing particular systems will create and share utility functions that can be utilized by the wider community.<br />
<br />
The default display style for ScriptCards output is similar to the format used to document player and NPC abilities in Dungeons and Dragons 4th Edition, but does not have any system ties to D&D4E.<br />
<br />
Current OneClick Version : 1.4.0e<br />
<br />
Current Development Version : 1.4.4<br />
<br />
'''''<big>Critically Important: ScriptCards does not use/parse inline rolls. ScriptCards includes its own built-in dice roll parser to allow for the use of variables inside dice rolls. As of version 1.2.3, ScriptCards will now take inline rolls and substitute the total result value in statement strings, meaning that you can utilize inline rolls but ScriptCards will only see the result of the roll, and not parse the roll components itself.</big>'''''<br />
<br />
* {{fpl|9752053/ ScriptCards thread}}<br />
** {{fpl|10000297/ Scritpcard API Working and Sharing}}<br />
* https://github.com/kjaegers/ScriptCards/tree/main/ScriptCards_API - GitHub repository for source before the one-click version is updated.<br />
* {{yt.be|hyR7Jnq4mQM ScriptCards Intro}} 45min, Jan 2021<br />
* {{yt.be|u50xvNzS9Zk ScriptCards Magic Missile Deep Dive}} 39min, Feb 2021<br />
<br />
<br />
__TOC__<br />
=== Is ScriptCards Related to [[PowerCards]]? ===<br />
<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
Check the '''[[#What to Know if you are Coming from PowerCards|What to Know if you are Coming from PowerCards]]'''-section for a comparison table between the two scripts.<br />
<br />
== What is a ScriptCard Script ==<br />
<br />
A ScriptCard Script is text written into the chat window (either typed directly, pasted, or run via a macro) that will produce a card of information in the [[text Chat|chat window]]. A ScriptCard Script is composed of an [[API]] command: <code><nowiki>!scriptcard {{ }}</nowiki></code> enclosing any number of lines that determine the output that will be added to the card. At it simplest, the following macro:<br />
<br />
<pre>!scriptcard {{ }}</pre><br />
<br />
Will produce just a title card that displays “ScriptCards” as the name:<br />
<br />
[[File:Scriptcard blank.png]]<br />
<br />
Of course, this is just the simplest type of macro and isn’t very useful. In order to produce useful output, we need to include lines between the <code><nowiki>{{</nowiki></code> and <code><nowiki>}}</nowiki></code> that direct the API script as to what it should do.<br />
<br />
== Structure of a ScriptCard Line ==<br />
<br />
All ScriptCard lines begin with two dashes, followed by an ''statement identifier character'' that lets ScriptCards what type of line it is. There are several of these, and they are detailed in the next section. After the line type identifier, a Tag name 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.<br />
<br />
Following the Tag is a vertical bar, and then the content of the line itself. Again, each type of line might interpret this content differently.<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Identifier !! Statement Type !! Tag !! Content !! Notes<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--/</nowiki> || Comment || unused || unused || The <code>--/</code> 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--#</nowiki> || 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").<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--+</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--=</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--&</nowiki> || Assign String 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. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--@</nowiki> || 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 (i.e., [[TokenMod|!token-mod]], or [[ChatSetAttr|!setattr]], etc.)<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--:</nowiki> || 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<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--^</nowiki> || Branch To || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--></nowiki> || Call Procedure || 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<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--<</nowiki> || 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.<br />
|- <br />
| style="white-space:nowrap" | <nowiki>--?</nowiki> || Conditional Branch || Condition to be evaluated || True Branch Label<nowiki>|</nowiki>False Branch Label || The condition will be evaluated and execution will jump to one of the two indicated branches (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 included a semicolon separated list of parameters. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--s</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--l</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--v</nowiki> || 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+'''''<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--e</nowiki> || Echo to Chat || Name to send chat command as || Chat message to send || Variable substitution takes place on the tag and content.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--R</nowiki> || Retrieve Repeating Section Row information || "find", "first", or "next" || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--~</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--c</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--i</nowiki> || Information Request || User Prompt;Button Caption || InfoType;VariableName;ParameterText || See full documentation below.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--d</nowiki> || 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. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--%</nowiki> || 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. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--*</nowiki> || 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.<br />
|}<br />
<br />
== ScriptCard Statement Type Details ==<br />
The sections below detail the individual statement types supported by ScriptCards<br />
<br />
=== Comment (--/) ===<br />
<br />
A --/ statement is ignored by the ScriptCards parser. You can use this type of statement to add comments and informational text to your script. <br />
<br />
Example:<br />
<pre><br />
!script {{<br />
--/|Script Name : Fireball<br />
--/|Purpose : Allow the player to cast a fireball and blow stuff up!<br />
.<br />
.<br />
.<br />
}}<br />
</pre><br />
<br />
=== Set Parameter (--#) ===<br />
<br />
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.<br />
<br />
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.<br />
<br />
'''''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.'''''<br />
<br />
Examples:<br />
<pre><br />
--#title|Magic Missile<br />
--#leftsub|Level 1 Spell<br />
--#rightsub|Force Damage<br />
</pre><br />
<br />
The three examples above set the “title”, “leftsub”, and “rightsub” values for the card to the content value for the line. <br />
<br />
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.<br />
Settings Lines do not produce output lines on the card.<br />
<br />
The following settings are available (note that parameter names are ''not'' case sensitive):<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Name !! Effect/Use !! Default Value !! Type<br />
|-<br />
| 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<br />
|-<br />
| allowplaintextinrolls || If set to a non-zero value, plain character text in rolls will be copied to the roll text || 0 || Per-Line<br />
|-<br />
| bodyFontFace || Name of the font used in the card rows || Helvetica || Global<br />
|-<br />
| bodyFontSize || Size of the text in the card rows || 14px || Global<br />
|-<br />
| bodybackgroundimage || Specify an image (content for a CSS background-image tag) for the body area || none || Global<br />
|-<br />
| buttonBackground || Background color for buttons created with [button][/button] || #1C6EA4 || Per-Line<br />
|-<br />
| buttonBorderColor || Border (outline) color for buttons created with [button][/button] || #999999 || Per-Line<br />
|-<br />
| buttonFontFace || Font Family specifier for captions on buttons created with [button][/button] || Tahoma || Per-Line<br />
|-<br />
| buttonFontSize|| Text size for captions on buttons created with [button][/button] || x-small || Per-Line<br />
|-<br />
| buttonTextColor|| Text color of labels on buttons created with [button][/button] || #FFFFFF || Per-Line<br />
|-<br />
| 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<br />
|-<br />
| deferralcharacter || Changes the meta script deferral sequence to the specified value || ^ || Per-Line<br />
|-<br />
| diceFontColor|| Color of the dice created with the [d4] [d6], etc. formatting markers || #1C6EA4 || Per-Line<br />
|-<br />
| dicefontsize || Size of the dice created with the [d4] [d6], etc. formatting markers || 3.0em || Per-Line<br />
|-<br />
| 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<br />
|-<br />
| disablerollprocessing || If set to a non-zero value, --= lines will not process dice rolls strings || 0 || Per-Line<br />
|-<br />
| emoteBackground || Background color of the emote area || #f5f5ba || Global<br />
|-<br />
| emoteFont || Name of the font used in emote area (above the title of the output card) || Georgia || Global<br />
|-<br />
| emoteFontColor || Color of the font in the emote area || None (Empty) || Global<br />
|-<br />
| emoteFontSize || Size of the font used in the emote area || 14px || Global<br />
|-<br />
| emoteFontWeight || Font weight for the font in the emote area || bold|| Global<br />
|-<br />
| emoteState || If set to anything other than "visible", the emote portion of the card will not be displayed || visible || Global<br />
|-<br />
| emoteText || Text to display in the emote portion of the card || None (Empty) || Global<br />
|-<br />
| emotefont || Name of the font used in the emote text area || font-family: Georgia, serif; font-weight: bold; || Global<br />
|-<br />
| evenRowBackground || Hex code for the background color for even rows || #eeeeee || Per-Line<br />
|-<br />
| evenRowFontColor || Hex code for the text color for even rows || #000000 || Per-Line<br />
|-<br />
| evenrowbackgroundimage || Specify an image (content for a CSS background-image tag) for the even card rows || none || Per-Line<br />
|-<br />
| executionlimit || Maximum number of script lines the interpreter will try to execute. This prevents "infinite loop" sandbox crashes || 40000 || Global<br />
|-<br />
| hideCard || If set to any non-default value, the entire card output will be suppressed || 0 || Global<br />
|-<br />
| 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<br />
|-<br />
| 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<br />
|-<br />
| lineheight || Vertical size of each line on the output card || normal || Per-Line<br />
|-<br />
| nominmaxhighlight || If set to anything other than "0", rolls will not display crit/fumble/mixed highlight colors. || 0 || Per-Line<br />
|-<br />
| norollhighlight || If set to anything other than "0", rolls will not be formatted (plain numbers) but will still get a tooltip with details ('''''v1.3.6b+''''') || 0 || Per-Line<br />
|-<br />
| oddRowBackground || Hex code for the background color for even rows || #d0e4f5 || Per-Line <br />
|-<br />
| oddRowFontColor || Hex code for the text color for odd rows || #000000 || Per-Line<br />
|-<br />
| oddrowbackgroundimage || Specify an image (content for a CSS background-image tag) for the odd crd rows || none || Per-Line<br />
|-<br />
| reentrant || Used to name a script for rentrant button use || 0 || Global<br />
|-<br />
| 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)0 || Global<br />
|-<br />
| rollhilightlineheight || Determines the height of the hilight box placed around roll results ('''''1.4.2+''''') || 1.0em || Per-Line<br />
|-<br />
| roundUp || If set to a non-default value, integer division will round up instead of down || 0 || Per-Line<br />
|-<br />
| showfromfornonwhispers || If set to a non-zero value, will include the sender on cards that aren't whispered || 0 || Global<br />
|-<br />
| 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<br />
|-<br />
| subtitleFontColor || Color of the text in the subtitle areas || #FFFFFF || Global<br />
|-<br />
| subtitleFontFace || Name of the font used on the subtitle sections || Tahoma || Global<br />
|-<br />
| subtitleFontSize || Size of the subtitle font || 13px || Global<br />
|-<br />
| subtitleSeperator || The character(s) that will be placed between leftsub and rightsub || <nowiki>&#x2666</nowiki>; || Global<br />
|-<br />
| tableBorderRadius || CSS specifier for how rounded the borders of the output card are. Use "0px;" for square borders || 6px; || Global<br />
|-<br />
| tableShadow || CSS specifier for the drop shadow under the output card || 5px 3px 3px 0px #aaa; || Global<br />
|-<br />
| tablebgcolor || Background color of the whole card. '''''Normally not visible''''' || #EEEEEE || Global<br />
|-<br />
| tableborder || Color of the border that surrounds the whole card || 2px solid #000000; || Global<br />
|-<br />
| 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<br />
|-<br />
| timezone || IANA Specifier for the local time zone, used in system/date functions || merica/New_York || Per-Line<br />
|-<br />
| title || Text displayed in the title area of the card || ScriptCards || Global<br />
|-<br />
| titleCardBackground || A hex color code representing the background color of the title area. || #1c6ea4 || Global<br />
|-<br />
| titleFontColor || Color of the text on the card title || #FFFFFF || Global<br />
|-<br />
| titleFontFace || Name of the font used on the title area || Contrail One || Global<br />
|-<br />
| titleFontLineHeight || Line spacing on the title area || 1.2em || Global<br />
|-<br />
| titleFontSize || Size of the title font || 1.2em || Global<br />
|-<br />
| titlecardbackgroundimage || Specify an image (content for a CSS background-image tag) for the title card area || none || Global<br />
|-<br />
| titlecardbottomborder || Border CSS specifier for the bottom of the title card area || 2px solid #444444; || Global<br />
|-<br />
| titlecardgradient || If set to non-zero value, will place a vertical gradient on the title card area || 0 || Global<br />
|-<br />
| usehollowdice || If set to a non-zero value, the hollow/outline versions of the dice fonts will be used || 0 || Per-Line<br />
|-<br />
| whisper|| Comma separated list of who to whisper the output to. Use "gm" for [[GM|GMs]] and "self" for the sender || none || Global|}<br />
|}<br />
<br />
''Setting Lines do not produce output lines on the card''<br />
<br />
=== Direct Output (--+) ===<br />
<br />
A direct output line display 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.<br />
<br />
Examples of Direct Output lines:<br />
<pre><br />
--+Hello|World<br />
--+Attack|The monster rolls [$Attack] to hit!<br />
--+Damage|@{target|token_name} is hit for [$Damage] [#3333AA][b]frost[/b][/#] damage.<br />
</pre><br />
<br />
Direct Output lines support inline formatting, roll variable replacement, character attribute references, and procedure variables.<br />
<br />
=== GM Output (--*) ===<br />
<br />
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. <br />
<br />
Example:<br />
<pre><br />
--+PlayerLine|This line is shown on the public card<br />
--*GMLine|This line will only be shown to GMs, on a separate card.<br />
</pre><br />
<br />
=== Roll Variable Assignment (--=) ===<br />
<br />
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.<br />
<br />
'''''All components of a roll equation should be separated with spaces.'''''<br />
<br />
Examples:<br />
<pre><br />
--=MissileDamage|1d4 + 1<br />
--=Attack|1d20 + @{selected|strength_mod} [STR] + @{selected|pb} [PROF]<br />
</pre><br />
<br />
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. Text enclosed in square brackets ([]) is considered "flavor text" and will be added to the result text but does not impact the roll result.<br />
<br />
The following dice formats are supported:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Format Pattern !! Example !! Description<br />
|-<br />
| XdY || 3d8 || Simple format. Roll a Y-sided die X times<br />
|-<br />
| XdYkhZ || 2d20kh1 || Roll Y-sided die X times and keep the highest Z number of dice<br />
|-<br />
| XdYklZ || 4d6kl3 || Roll Y-sided die X times and keep the lowest Z number of dice <br />
|-<br />
| XdY>Z || 5d6>3 || Roll Y-sided die X times and count a 1 for each roll greater than Z <br />
|-<br />
| XdY<Z || 5d6<3 || Roll Y-sided die X times and count a 1 for each roll less than Z <br />
|}<br />
<br />
'''''Note: The dice formulae below are supported in the development version of ScriptCards and will be merged with the table above when activated on OneClick'''''<br />
::{| class="wikitable"<br />
|-<br />
! Format Pattern !! Example !! Description<br />
|-<br />
| 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<br />
|-<br />
| 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<br />
|-<br />
| 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)<br />
|-<br />
| 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<br />
|}<br />
<br />
The following operators are supported in a roll equation:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Operator !! Operation<br />
|-<br />
| + || Addition <br />
|-<br />
| - || Subtraction <br />
|-<br />
| * || Multiplication <br />
|-<br />
| / || Division <br />
|-<br />
| \ || Integer Division (Rounds down) <br />
|-<br />
| % || Modulo (Remainder of Divison)<br />
|}<br />
<br />
Roll Variables can be accessed at any time after they have been created by using the [$VariableName] format, with the following optional modifiers:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Modifier !! Meaning<br />
|-<br />
| No modifier || In a Direct Output Line (<nowiki>--+</nowiki>) 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<br />
|-<br />
| .Total || The end result of the roll equation as an unformatted number <br />
|-<br />
| .Base || The cumulative result of any dice rolled in the Roll Text (Numeric modifiers are not included) <br />
|-<br />
| .Ones || The number of dice in the roll that came up as 1s <br />
|-<br />
| .Aces || The number of dice in the roll that came up as the maximum number on the die <br />
|-<br />
| .Odds || The number of dice in the roll that came up with an odd number <br />
|-<br />
| .Evens || The number of dice in the roll that came up with an even number <br />
|-<br />
| .RollText || The raw text of the roll that was use to generate the results <br />
|-<br />
| .Text || A text representation of the results of the roll, including the numbers rolled for each die <br />
|-<br />
| .tableEntryText || The text portion of the result of a table roll<br />
|-<br />
| .tableEntryImgURL || The image source portion of the result of a table roll<br />
|-<br />
| .tableEntryValue || Numeric value of tableEntryText (via parseInt). If a non-numeric value, will be 0<br />
|-<br />
| .Raw || The total numeric result without any formatting, even if placed somewhere formatting would normally be done. <br />
|}<br />
<br />
Examples:<br />
<pre><br />
--+Total Damage|[$MissileDamage.Total] (roll was 1d4+1)<br />
--+Base Damage|[$MissileDamage.Base] (without the +1)<br />
--=Attack|1d20 + @{selected|strength_mod} [STR] + @{selected|pb} [PROF] + [$BlessBonus] [Bless]<br />
</pre><br />
<br />
In this case, 1d4 will be rolled and stored in “BlessBonus”, which can then be used in the Attack line.<br />
<br />
'''''Mathematical Functions in Roll Expressions '''''<br />
<br />
The ScriptCards roll parser works from left to right, always maintaining a current value and applying whatever comes next to the total. The following in-line functions to the roll parser. These are:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Expression !! Meaning<br />
|-<br />
| {ABS} || Absolute Value<br />
|-<br />
| {CEIL} || Ceiling value (round up to the next whole number)<br />
|-<br />
| {FLOOR} || Floor value (round down to the next whole number)<br />
|-<br />
| {ROUND} || Round value (round up if the decimal portion is greater than 0.5, otherwise round down)<br />
|-<br />
| {NEGATE} || Multiply the value by negative one.<br />
|-<br />
| {SQRT} || Take the square root of the running value. ('''''1.4.1+''''')<br />
|-<br />
| {SQUARE} || Square the running value. ('''''1.4.2+''''')<br />
|-<br />
| {CUBEROOT} || Take the cube root of the running value. ('''''1.4.2+''''')<br />
|-<br />
| {CUBE} || Cube the running value. ('''''1.4.2+''''')<br />
|-<br />
| {SIN} || Return the SIN of running value. ('''''1.4.2+''''')<br />
|-<br />
| {COS} || Return the COS of running value. ('''''1.4.2+''''')<br />
|-<br />
| {TAN} || Return the TAN of running value. ('''''1.4.2+''''')<br />
|-<br />
| {ASIN} || Return the ASIN of running value. ('''''1.4.2+''''')<br />
|-<br />
| {ACOS} || Return the ACOS of running value. ('''''1.4.2+''''')<br />
|-<br />
| {ATAN} || Return the ATAN of running value. ('''''1.4.2+''''')<br />
|}<br />
<br />
<br />
'''''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 <nowiki>[[ ]]</nowiki> 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.<br />
<br />
'''''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.<br />
<br />
'''Rolling on Rollable Tables'''<br />
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.<br />
<br />
''Roll Variable Lines do not produce output lines on the card.''<br />
<br />
=== String Variable Assignment (--&) ===<br />
<br />
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:<br />
<br />
<pre><br />
--&MyText|Hello<br />
</pre><br />
<br />
Here, we assign the text "Hello" to the string variable named MyText. You can also append text to a string variable by prefixing the content with a + sign:<br />
<br />
<pre><br />
--&MyText|+ World<br />
</pre><br />
<br />
If run after the statement above, MyText will now contain "Hello World".<br />
<br />
String variables can be referenced using the syntax [&variablename]<br />
<br />
=== Call API (--@) ===<br />
<br />
ScriptCards can use a Call API instruction to execute other API commands. The Tag contains the API 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 API command is executed.<br />
<br />
Examples:<br />
<pre><br />
--@eh|list<br />
--@alter|_target|@{target|token_id} _bar|3 _amount|-[$Damage]<br />
</pre><br />
<br />
In the first example above, the command <code>!eh list</code> will be executed, calling [[EncounterHelper]]. In the second, {{fpl|1216260/ AlterBars}} is called to modify a token's Bar 3 value.<br />
<br />
'''''Note:''''' When ScriptCards (or any API script) runs other API 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).<br />
<br />
See [[API:Script Index]] for more options.<br />
<br />
=== Branch Label (--:) ===<br />
<br />
A branch label defines a line in your code that can be reached by one of the branching instructions (<nowiki>--^</nowiki>, <nowiki>--></nowiki>, or <nowiki>--?</nowiki>). The Tag serves as the label name, and must be unique on the card.<br />
<br />
The vertical bar (|) separator must be present, but the content portion of the line is unused and can be treated as a comment.<br />
<br />
Examples:<br />
<pre><br />
--:MyLoop|<br />
--:CriticalHit|Will jump here if we roll a critical hit!<br />
</pre><br />
<br />
''A Branch Label line does not produce an output line on the card.''<br />
<br />
=== Branch (--^) === <br />
<br />
A Branch line 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.<br />
<br />
Examples:<br />
<pre><br />
--^MyLoop|Jumps to MyLoop<br />
--^SkipCrit|We didn't crit, so skip the Crit code<br />
</pre><br />
<br />
''A Branch line does not produce an output line on the card.''<br />
<br />
=== Call Procedure (-->) ===<br />
<br />
Similar to a branch, a Call Procedure (sometimes knows 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 (<nowiki>--<</nowiki>) 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 (;).<br />
<br />
Examples:<br />
<pre><br />
-->FixFormat|#3333FF;#999999<br />
</pre><br />
<br />
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%].<br />
<br />
=== Return (--<) ===<br />
<br />
A return instruction marks the end of a Gosub procedure. 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.<br />
<br />
Examples:<br />
<pre><br />
--<|<br />
--<|End of MySub<br />
</pre><br />
<br />
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.<br />
<br />
=== Conditional Statement (--?) ===<br />
<br />
A conditional statement contains some equation in the Tag that will be evaluated. '''''If any part of the comparison can/does contain a space, it needs to be surrounded by double quotes'''''<br />
<br />
Based on the true/false result of the evaluation, one of two execution paths will be taken. These execution paths are detailed in the content section of the statement. The "if true" path is specified first (directly after the vertical bar), and the "if false" path is specified after it, also separated by a vertical bar.<br />
<br />
Example:<br />
<pre><br />
--?[$AttackRoll.Total] -ge [$TargetAC]|Hit|Miss<br />
</pre><br />
<br />
'''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.'''<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Branch Format !! Meaning<br />
|-<br />
| Label || If just a label is specified, execution will branch to that label when the comparison is matched.<br />
|-<br />
| >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 <br />
|-<br />
| =VariableName || The roll variable "VariableName" will be assigned the value following a semicolon (ex: --?1 -eq 1|=Roll;1d20)<br />
|-<br />
| &VariableName || The string variable "VariableName" will be assigned the value following a semicolon (ex: --?1 -eq 1|&Result;Hit|&Result;Miss)<br />
|-<br />
| % or %! || The current for...next loop will perform the "next" action (%) or will break out (%!) <br />
|-<br />
| [ || Code block (see below)<br />
|}<br />
<br />
Examples:<br />
<pre><br />
--?[$AttackRoll.Base] -eq 20|CriticalHit<br />
--?[$AttackRoll.Base] -eq 1|>Fumble;@{selected|dexterity_mod}<br />
--?"@{target|npc_type}" -inc "undead"|&MonsterType;Undead|&MonsterType;Not Undead<br />
--?[$Attack.Total] >= [$ArmorClass]|>Hit|>Miss<br />
</pre><br />
<br />
In the first example, if the Base value of AttackRoll is a 20 (natural 20 on the die) execution will branch to the CriticalHit label.<br />
<br />
In the second example, 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%].<br />
<br />
The third example looks for the word "undead" in the npc_type attribute of the targeted character. If it exists in the text, the MonsterType string variable will be set to "Undead", otherwise it will be set to "Not Undead". <br />
<br />
The final example would call 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.<br />
<br />
''Text that does/may contain a space should be enclosed in double quotes.''<br />
<br />
The following comparison operators are available:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Comparator !! Meaning<br />
|-<br />
| -eq || Equal To <br />
|-<br />
| -eqi || Case insensitive Equal To <br />
|-<br />
| -ne || Not Equal To <br />
|-<br />
| -nei || Case insensitive Not Equal To <br />
|-<br />
| -gt || Greater Than <br />
|-<br />
| -ge || Greater Than or Equal To <br />
|-<br />
| -lt || Less Than <br />
|-<br />
| -le || Less Than or Equal To <br />
|-<br />
| -inc || Includes (text strings). <br />
|-<br />
| -ninc || Does Not Include (text strings). <br />
|}<br />
<br />
Multi-part conditionals are supported with -and and -or as separators. For example:<br />
<br />
<pre><br />
--?[$Attack.Total] -ge @{target|npc_ac} -and [$Attack.Base] -ne 20|HitButNotCrit<br />
</pre><br />
<br />
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):<br />
<br />
true AND false OR true<br />
<br />
Will be evaluated as true. The first two (true and false) will be false, but then false OR true will be true.<br />
<br />
Conversely:<br />
<br />
true or false and false<br />
<br />
Will be false, because the first true and false will evaluate to true, and then true and false will be false.<br />
<br />
'''CODE BLOCKS'''<br />
<br />
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.<br />
<br />
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:<br />
<br />
<pre><br />
!script {{<br />
--=Roll|1d2<br />
--+Roll|[$Roll]<br />
--?[$Roll.Total] -eq 2|[<br />
--&Value|Yep!<br />
--+|We are inside the TRUE portion of the block<br />
--]|[<br />
--&Value|Nope<br />
--+|We are inside the FALSE portion of the block<br />
--]|<br />
--+After|the blocks!<br />
--+Value|[&Value]<br />
}}<br />
</pre><br />
<br />
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 --]|. <br />
<br />
At this time, blocks cannot be nested, and can only be created as part of a conditional (--[ is not a valid statement type)<br />
<br />
''A conditional statement does not produce a line of output on the card.''<br />
<br />
=== Case Statement (--c) ===<br />
<br />
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 (:). Each match condition includes a branch label that will be used if the test value matches the item. 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:<br />
<br />
<pre><br />
!script {{<br />
--#title|Case Statement Testing<br />
--=Roll|1d4<br />
--C[$Roll.Total]|1:>One;[$Roll]|2:>Two;[$Roll]|3:>Three;[$Roll]|4:>Four;[$Roll]<br />
--X|<br />
<br />
--:One| --+Value|was One ([%1%]) --<|<br />
--:Two| --+Value|was Two ([%1%]) --<|<br />
--:Three| --+Value|was Three ([%1%]) --<|<br />
--:Four| --+Value|was Four ([%1%]) --<|<br />
}}<br />
</pre><br />
<br />
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 variable as a parameter.<br />
<br />
=== Save and Load (--s and --l) ===<br />
<br />
This statement pair is used to either store (--s) or load (--l) data from persistent storage. Items stored in persistent storage remain between card rolls and between Roll20 sessions. There are two types of data that can be stored: settings and roll variables. <br />
<br />
Examples:<br />
<br />
<pre><br />
--Ssettings|GreenStyle<br />
--Srollvariables|FirstCardVars<br />
</pre><br />
<br />
In this case, the tag for the statement determines what type of item is being saved (settings or rollvariables). When saving settings, all non-default settings are written to the named setting storage value. When Roll Variables are saved, all variables that currently exist will be saved to the named storage value.<br />
<br />
Loading stored items simply requires the same command with the --l statement type:<br />
<br />
<pre><br />
--Lsettings|GreenStyle<br />
--Lrollvariables|FirstCardVars<br />
</pre><br />
<br />
When loading settings, all stored settings will be applied to the current card settings. You can override settings by changing them after the load.<br />
<br />
When loading roll variables, the saved variables will be added to (or overwrite if they have the same name) any variables on the current card. This means it is safe to create roll variables before the load statement.<br />
<br />
'''Practical Uses'''<br />
The major intended use of persistent storage is for storing card formats for use in later scripts. For example, the following script:<br />
<br />
<pre><br />
!scriptcard {{<br />
--#titlecardbackground|#22CC22<br />
--#oddrowbackground|#cceecc<br />
--#evenrowbackground|#99ee99<br />
--Ssettings|@{selected|token_name}<br />
}}<br />
</pre><br />
<br />
Would save the titlecardbackground, oddrowbackground, and evenrowbackground settings to a saved list named after the selected token's name. When creating cards for that token to run later, you could include the line:<br />
<br />
<pre><br />
--Lsettings|@{selected|token_name}<br />
</pre><br />
<br />
To load all of the settings at once. By creating these setting sets for each character, you can specify a different color scheme for each character that can then be used in cards with a single formatting line.<br />
<br />
There is a supplemental ! command added to support saved settings:<br />
<br />
<pre><br />
!sc-liststoredsettings<br />
</pre><br />
<br />
Will produce a list of all stored setting names, with buttons to list the setting values stored in each group and a button to delete groups as needed.<br />
<br />
=== Visual Effects (--v) ===<br />
<br />
The --v statement can be used to create visual effects on the tabletop. The tag portion of the statement can be either "token" or "betweentokens". The content portion of the statement contains the required parameters for the effect generation, separated by spaces. If the effect is "none", no effect will be played. If any other value that doesn't match a Roll20 effect name will result in a burst-fire effect.<br />
<br />
For "token" effects, the parameters are the token id for the token the effect happens on, followed by the effect specifier.<br />
<br />
Example:<br />
<pre><br />
--vtoken|@{selected|token_id} burst-fire<br />
</pre><br />
<br />
For "betweentoken" effects, the parameters are the source token id, the target token id, and the effect specifier.<br />
<br />
Example:<br />
<pre><br />
--vbetweentokens|@{selected|token_id} @{target|token_id} beam-magic<br />
</pre><br />
<br />
'''''Version 1.2.8+'''''<br />
<br />
An additional effect specifier, "point" is available in 1.2.8+. This specifier allows you to create a visual effect at a designated X/Y pixel coordinate. Future updates will add custom-vfx support to this option. The parameters are the X and Y coordinates and the effect descriptor. As of version 1.2.9, you can also use custom effect specifiers with Point effects:<br />
<br />
<pre><br />
--vpoint|150 200 burst-fire<br />
</pre><br />
<br />
=== Echo to Chat (--e) ===<br />
<br />
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.<br />
<br />
Example:<br />
<pre><br />
--eThe Ghost|/em hovers around @{selected|character_name}... BOO!<br />
</pre><br />
<br />
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).<br />
<br />
'''''Whispering'''''<br />
<br />
You can use the echo statement to send a whisper, but there's a trick to it. If you execute this code here:<br />
<br />
<pre><br />
--eThe Ghost|/w ExamplePlayerName Boo.<br />
</pre><br />
<br />
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.<br />
<br />
So, in conclusion, it's best to use something like this when you're sending a whisper:<br />
<br />
<pre><br />
!script {{<br />
--#hidecard|1<br />
--&sender|The Ghost<br />
--&receiver|ExamplePlayerName<br />
--&message|Boo.<br />
--e[&sender]|/w [&receiver] [&message]<br />
--eScriptCards|/w gm **Whispered from [&sender] to [&receiver]:** [&message] <br />
}}<br />
</pre><br />
<br />
This will ensure that the message appears in your chat feed as well.<br />
<br />
=== Repeating Section Access (--R) ===<br />
<br />
ScriptCards (as of v0.0.13) supports accessing repeating section rows on a character sheet with the --R statement type. <br />
<br />
There are three basic commands you can use with --R, and they are specified by the tag used:<br />
<br />
<pre><br />
--Rfind|characterid;EntryName;SectionPrefix;SearchField<br />
</pre><br />
<br />
This is the most direct way to access a repeating section row. Supplying the character ID, followed by what you are looking for (Greatsword, for example), followed by the character sheet's section prefix (repeating_attack), followed by the field to check what you are searching for (atkname) will load the matching section (if found) into the script parsers memory. For example:<br />
<br />
<pre><br />
--Rfind|@{selected|character_id};Greatsword;repeating_attack;atkname<br />
</pre><br />
<br />
Will look at the character's "repeating_attack" section for an entry with an atkname value equal to "Greatsword". Similarly:<br />
<br />
<pre><br />
--Rfind|@{selected|character_id};Bite;repeating_npcaction;name<br />
</pre><br />
<br />
Will look for a "Bite" action on an NPC's action list.<br />
<br />
<pre><br />
--Rfirst|characterid;section prefix<br />
</pre><br />
<br />
This form of the --R command will look at all of the entries in the specified repeating section and load the first one into memory:<br />
<br />
<pre><br />
--Rfirst|@{selected|character_id};repeating_attack<br />
</pre><br />
<br />
Would load the character's first "repeating_attack" row into memory.<br />
<br />
<pre><br />
--Rnext|<br />
</pre><br />
<br />
No parameters are required for --Rnext, which loads the next entry in the list that was obtained with "first" into memory.<br />
<br />
However a row is obtained, it will be parsed to replace any attribute references (ie, @{level}) with the corresponding character attribute.<br />
<br />
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".<br />
<br />
You can reference repeating attribute data using the syntax [*R:attributename] syntax (similar to referencing standard character attributes).<br />
<br />
Here are some examples:<br />
<br />
Display the details of the "Greatsword" PC attack:<br />
<br />
<pre><br />
!script {{<br />
--Rfind|@{selected|character_id};Greatsword;repeating_attack;atkname<br />
--+Attack Name|[*R:atkname]<br />
--+Base Damage|[*R:dmgbase]<br />
}}<br />
</pre><br />
<br />
[[File:Scriptcards repeating greatsword.png|Repeating Greatsword Attack]]<br />
<br />
List all of the actions an NPC can take (just actions, not legendary, etc.)<br />
<br />
<pre><br />
!script {{<br />
--#title|NPC Actions<br />
--#leftsub|@{selected|token_name}<br />
--Rfirst|@{selected|character_id};repeating_npcaction<br />
--:DisplayLoop|<br />
--?"[*R:name]" -eq NoRepeatingAttributeLoaded|Done<br />
--+Action:|[*R:name] [*R:attack_damage] [*R:attack_damagetype]<br />
--?"[*R:attack_damage2]" -eq ""|NoSecondaryDamage<br />
--+ |[*R:attack_damage2] [*R:attack_damagetype2]<br />
--:NoSecondaryDamage|<br />
--Rnext|<br />
-->DisplayLoop| <br />
--:Done|<br />
}}<br />
</pre><br />
<br />
[[File:Scriptcards repeating npcactions.png]]<br />
<br />
In the script above, we get the "first" repeating_npcaction and display information about it. We then execute "next" and repeat until we run into "NoRepeatingAttributeLoaded".<br />
<br />
'''''Special debugging command: dump'''''<br />
<pre><br />
--Rdump|<br />
</pre><br />
<br />
The "dump" command will list all of the attributes ScriptCards knows about for the currently loaded repeating row to the API Console Log.<br />
<br />
=== Assign Variable to Built-In Function (--~) ===<br />
<br />
ScriptCards has the ability to run a function built into the API script and return the results to a variable. Some functions return roll variables, while others return strings. See the function table below for details. The format is:<br />
<br />
--~VariableName|function;param1;param2;param3;...<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Function Name !! Parameters !! Description<br />
|-<br />
| distance || token_A_ID;token_B_ID || Calculate the Chebyshev distance in grid units between two tokens. This is the measurement scheme D&D 4E/5E use for diagonal distance measurement<br />
|-<br />
| euclideandistance || token_A_ID;token_B_ID || Calculate the Euclidean distance between two tokens. This is essentially the Pythagorean theorem in action. Returns the result in grid units.<br />
|-<br />
| euclideanpixel || token_A_ID;token_B_ID || Calculate the Euclidean distance between two tokens and returns the result is pixels instead of grid units. <br />
|-<br />
| euclideanlong || token_A_ID;token_B_ID || 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 is calculated instead of before. More accurate over long distances. <br />
|-<br />
| manhattandistance || token_A_ID;token_B_ID || Also called "taxicabdistance" (which is an acceptable function name), this measures to how-many-over, how-many-up/down distance, disallowing diagonal movement.<br />
|-<br />
| getselected || none || 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 the first selected token, VariableName2 the second, etc.<br />
|}<br />
<br />
'''''Functions with Sub Functions'''''<br />
<br />
Most ScriptCards functions are grouped into set as sub functions. The table below lists the major functions and their sub functions.<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Function Name !! Sub Function !! Parameters !! Return Type !! Description<br />
|-<br />
| array || define || arrayname;value1;value2;... || none || Creates an array called "arrayname" and adds value1, value2, etc. to the array<br />
|-<br />
| array || sort || arrayname || none || Sorts the specified array in place in ascending order<br />
|-<br />
| array || add || arrayname;value1;value2;... || none || Adds value1, value2, ... to the existing array "arrayname"<br />
|-<br />
| array || remove || arrayname;value1;value2;... || none || Removes value1, value2, ... from the existing array "arrayname". Resets the array index to 0.<br />
|-<br />
| array || replace || arrayname;currentvalue;newvalue || none || Replaces all occurrences of "currentvalue" in "arayname" with "newvalue"<br />
|-<br />
| array || setatindex || arrayname;index;newvalue || none || Replaces the array item at index "index" with "newvalue"<br />
|-<br />
| array || getindex || arrayname || stringVariable || Retrieves the current index in "arrayname" and stores it in the supplied string variable<br />
|-<br />
| array || setindex || arrayname;newindex || none || Sets the current index in array "arrayname" to "newindex"<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| array || removeat || arrayname;indexposition || none || Removes the item at index "indexposition" from "arrayname". Resets the current array index to 0.<br />
|-<br />
| array || indexof || arrayname;searchvalue || stringVariable || Searches the array "arrayname" for and item with the value of "searchvalue" and, if found, returns the index of the first matching value or "ArrayError" if not found<br />
|-<br />
| array || getlength || arrayname || stringVariable || Returns the number of items in array "arrayname"<br />
|-<br />
| array || pagetokens || arrayname;tokenid;(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. 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.)<br />
|-<br />
| 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.<br />
|-<br />
| array || stringify || arrayname || stringVariable || Returns all of the items in "arrayname" as a string separated by semicolons (;)<br />
|-<br />
| array || fromstring || arrayname || delimiter;string || Creates an array from "string", splitting "string" on "delimiter" to separate the items<br />
|-<br />
| array || statusmarkers|| arrayname;tokenid || none|| Creates an array (arrayname) of the active statusmarkers (sometimes called Token Markers) for the specified tokenid<br />
|-<br />
| math || angle || math;angle;tokenid;tokenid|| rollVariable || Calculates the angle between two tokens and returns the value in degrees<br />
|-<br />
| math || ceil || math;ceil;value || rollVariable || Rounds '''value''' up to the next integer, dropping any decimal portion of the number<br />
|-<br />
| math || clamp || math;clamp;value;lowerBound;upperBound || rollVariable || Returns '''value''', but restricted to the range of '''loweBound''' and '''upperBound'''.<br />
|-<br />
| math || floor || math;floor;value || rollVariable || Rounds '''value''' down, dropping any decimal portion of the number<br />
|-<br />
| math || max || math;max;valueA;valueB || rollVariable || Returns the larger of '''valueA''' vs '''valueB'''<br />
|-<br />
| math || min || math;min;valueA;valueB || rollVariable || Returns the smaller of '''valueA''' vs '''valueB'''<br />
|-<br />
| math || round || math;round;value || rollVariable || Rounds '''value''' to the nearest integer<br />
|-<br />
| string || length || string;length;stringValue || rollVariable || Returns the length of '''stringValue''' in characters<br />
|-<br />
| string || before || string;before;searchText;stringValue || stringVariable || Searches '''stringValue''' for '''searchText''' and returns the portion of '''stringValue''' prior to that text<br />
|-<br />
| string || after || string;after;searchText;stringValue || stringVariable || Searches '''stringValue''' for '''searchText''' and returns the portion of '''stringValue''' after that text<br />
|-<br />
| string || left || string;left;count;stringValue || stringVariable || Returns the leftmost '''count''' characters of '''stringValue'''<br />
|-<br />
| string || right || string;right;count;stringValue || stringVariable || Returns the rightmost '''count''' characters of '''stringValue'''<br />
|-<br />
| string || replace || string;replace;searchText;replaceText;stringValue || stringVariable || Replaces '''searchText''' in '''stringValue''' with '''replaceText''' and returns the resulting string<br />
|-<br />
| string || replaceall || string;replace;searchText;replaceText;stringValue || stringVariable || Replaces all intances of '''searchText''' in '''stringValue''' with '''replaceText''' and returns the resulting string '''''Requires 1.2.9+'''''<br />
|-<br />
| string || trim || string;trim;stringValue || stringVariable || Removes leading and trailing spaces from stringValue and returns the result. <br />
|-<br />
| string || substring || string;substring;start;count;stringValue || stringVariable || Returns '''count''' characters starting at '''start''' from '''stringValue'''<br />
|-<br />
| 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.<br />
|-<br />
| string || tolowercase || string;tolowercase;stringValue || stringVariable || Converts the passed string to lower case and assigns to the passed variable name. <br />
|-<br />
| string || touppercase || string || stringVariable || Converts the passed string to upper case and assigns to the passed variable name. <br />
|-<br />
| 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. <br />
|-<br />
| 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.<br />
|-<br />
| 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'''.<br />
|-<br />
| turnorder || clear || none || none || Clears all entries from the {{Turn Tracker}}/Initiative<br />
|-<br />
| turnorder || addtoken || tokenid;trackervalue || none || Adds the token represented by "tokenid" to the initiative tracker with an initiavie value of "trackervalue"<br />
|-<br />
| turnorder || replacetoken || tokenid;trackervalue || none || Replaces the token represented by "tokenid" in the initiative tracker with an initiavie value of "trackervalue". Will add the token if it doesn't exist in the tracker.<br />
|-<br />
| turnorder || removetoken || tokenid || none || Removes the token represented by "tokenid" from the initiative tracker if it exists<br />
|-<br />
| turnorder || addcustom || textlabel;trackervalue || none || Add a custom text entry to the {{Turn Tracker}}/Initiative named "textlabel" with an initiative value of "trackervalue"<br />
|-<br />
| system || date || getdatetime || stringVariable || Returns the date time in the active timezone (see settings) <br />
|-<br />
| system || date || getdate || stringVariable || Returns the date in the active timezone (see settings) <br />
|-<br />
| system || date || gettime || stringVariable || Returns the time in the active timezone (see settings)<br />
|-<br />
| system || dumpvariables || "rolls", "string", or "array" || none || Dumps all of the defined variables of the indicated type to the console log<br />
|-<br />
| system || findability || system;findability;charactername;abilityname || stringVariable || Returns the object ID of the ability on the indicated character or "AbilityNotFound"<br />
|-<br />
|}<br />
<br />
Examples:<br />
<br />
<pre><br />
--~HowFarAway|distance;@{selected|token_id};@{target|token_id}<br />
</pre><br />
<br />
Returns the distance (Chebyshev) between the selected and target tokens and stores it in "HowFarAway".<br />
<br />
<pre><br />
--SelectedDudes|getselected<br />
</pre><br />
<br />
If 5 tokens were selected, 6 variables would be created: SelectedDudesCount (with a value of 5), SelectedDudes1, SelectedDudes2, SelectedDudes3, SelectedDudes4, SelectedDudes5.<br />
<br />
=== Information Request (--i) ===<br />
<br />
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.<br />
<br />
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.<br />
<br />
After the user has clicked the button and responded to the requests, ScriptCards will resume processing the script from where it left off.<br />
<br />
Here is an example “i” line:<br />
<br />
<pre><br />
--IScriptCards needs additional information to continue;Click to select a target and provide information|t;MyNewTarget;Missile1Target||q;MyNameIs;What is your name?<br />
</pre><br />
<br />
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.<br />
<br />
Supported information request types are “t” for target token, and “q” for query.<br />
<br />
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).<br />
<br />
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:<br />
<br />
<pre><br />
q;UserName;What is your name?|Fred|Bob|Sally|Nancy<br />
</pre><br />
<br />
Would have a dropdown menu with four choices.<br />
<br />
== Inline Formatting ==<br />
<br />
Inline formatting is processed on Direct Output lines only (--+ lines) and the following inline format markup is available:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Formatting Tags !! Description<br />
|-<br />
| [b]..[/b] || Bold the text between the markers <br />
|-<br />
| [i]..[/i] || Italicize the text between the markers <br />
|-<br />
| [u]..[/u] || Underline the text between the markers <br />
|-<br />
| [s]..[/s] || Strike-Thru the text between the markers <br />
|-<br />
| [c]..[/c] || Center alignment <br />
|-<br />
| [l]..[/l] || Left alignment <br />
|-<br />
| [r]..[/r] || Right alignment <br />
|-<br />
| [j]..[/j] || Full justification alignment <br />
|-<br />
| [#xxx]..[/#] or [#xxxxxx]..[/#] || Use a 3 or 6 digit hex code to colorize the text between the markers <br />
|-<br />
| [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, <code>[img width=128 height=128]</code> )<br />
|-<br />
| [button]caption::action[/button] || Create a button with the label "caption" that performs the action defined by "action". <br />
|-<br />
| [t] || Converted to HTML table tag. Text after the "t" will be included inside the tag (width, border, etc)<br />
|-<br />
| [/t] || Converted to HTML close table tag.<br />
|-<br />
| [tr] || Converted to HTML table row tag. Text after the "tr" will be included inside the tag<br />
|-<br />
| [/tr] || Converted to HTML close table row tag.<br />
|-<br />
| [td] || Converted to HTML table cell tag. Text after the "tr" will be included inside the tag<br />
|-<br />
| [/td] || Converted to HTML close table cell tag.<br />
|}<br />
<br />
== Variables ==<br />
<br />
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. While it is possible to assign both a string and a roll variable the same name, doing so will likely result in confusion when looking at the script later, so it is not recommended.<br />
<br />
String Variables are assigned with the --& statement and are referenced using [&variableName] notation.<br />
<br />
Roll Variables are assigned with the --= statement, and the assignment value is always processed by the ScriptCards Roll Processor (resolves dice rolls, etc.)<br />
<br />
There are a handful of variables assigned automatically when a ScriptCard is executed. These are all string variables, and are:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Variable !! Value<br />
|-<br />
| SendingPlayerID || Contains the object ID of the player that sent the macro<br />
|-<br />
| SendingPlayerName || Contains the display name of the player<br />
|-<br />
| SendingPlayerColor || Contains the color code associated with the player<br />
|-<br />
| SendingPlayerSpeakingAs || The contents of the "Speaking As" dropdown window<br />
|-<br />
| SendingPlayerIsGM || Contains 1 if the player is a GM, and 0 if the player is NOT a GM<br />
|}<br />
<br />
== Arrays ==<br />
<br />
Arrays are a special type of variable, and are managed by the function (<nowiki>--~</nowiki> command). All of the array function commands follow the same pattern:<br />
<br />
<pre>--~variableName|array;subcommand;arrayname;param1;param2;param3;...</pre><br />
<br />
Not all array commands return anything to "variableName". The function table above will specify the return type of the command if any.<br />
<br />
There are a couple of different ways to create an array:<br />
<br />
The '''define''' array subcommand creates (or recreates) an array and assigns it values - one for each included parameter after the array name. For example:<br />
<br />
<pre>--~|array;define;Fruits;mango;peach;strawberry;apricot;banana;apple</pre><br />
<br />
will create an array called '''Fruits''' with 6 elements in the order listed in the command (mango, peach, etc.)<br />
<br />
You can also use two other subcommands to create arrays based on tokens:<br />
<br />
<pre>--~Count|array;pagetokens;Everybondy;@{selected|token_id}</pre><br />
<br />
and<br />
<br />
<pre>--~Count|array;selectedtokens;Selected</pre><br />
<br />
In both cases, arrays of tokens will be created, and a string variable called "Count" will be set to the number of tokens in the array. The '''pagetokens''' command returns (by default) all of the tokens on the page that contains the token passed as the parameter after the array name. You can filter the tokens that "pagetokens" includes in the array by appending an optional parameter describing the type of token you are looking for:<br />
<br />
<pre>--~Count|array;pagetokens;Everybondy;@{selected|token_id};npc</pre><br />
<br />
Will return only tokens on the page that represent characters that do not have a ''controlledby'' parameter set. The available options are "all" (default), "char", "graphic", "pc", and "npc".<br />
<br />
The '''selectedtokens''' command returns an array with all of the tokens that were selected when the script was called.<br />
<br />
You can also use an arbitrary string to create an array, specifying a delimiter with the '''fromstring''' command:<br />
<br />
<pre><br />
--&names|Fred<br />
--&names|+,Sally<br />
--&names|+,Ted<br />
--&names|+,Joyce<br />
--~|array;fromstring;,;[&names]<br />
</pre><br />
<br />
The above example builds a comma-separated string and then uses "fromstring" to create an array with 4 elements from it, specifying the comma as the delimiter.<br />
<br />
Finally, you can use the '''statusmarkers''' command to create an array with one entry for each active status marker on a specified token:<br />
<br />
<pre>--~|array;statusmarkers;Conditions;@{selected|token_id}</pre><br />
<br />
will create an array with one entry for each status active on the selected token. The array elements will be the internal name of the status (if you are using custom status marker packs, the names will be specified in the marker pack).<br />
<br />
'''Traversing Arrays'''<br />
<br />
Each array keeps track of an internal index position (starting at 0). Several commands let you manage this index:<br />
<br />
*'''getindex''' returns the current index value<br />
*'''setindex''' sets the index to the specified location in the array<br />
*'''getlength''' returns the number of elements in the array<br />
*'''indexof''' returns the index location of the specified element<br />
<br />
Other commands let you retrieve values from the array:<br />
<br />
*'''getfirst''' sets the index to 0 and returns the value at that position<br />
*'''getnext''' advances the index by 1 and returns the new current value<br />
*'''getprevious''' reduces the index by 1 and returns the new current value<br />
*'''getlast''' sets the index to the last elements in the array and returns the new current value<br />
<br />
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.<br />
<br />
'''Manipulating Array Elements'''<br />
<br />
Several array commands deal with inserting, removing, and modifying elements:<br />
<br />
*'''add''' works just like define, except that it takes an existing array and adds elements to it based on the passed parameters<br />
*'''remove''' looks for items matching each passed parameter and removes them from the indicated array if they exist<br />
*'''removeat''' allows you to specify an index location in the array and remove the element at that position<br />
*'''replace''' searches an array for a value and replaces all occurrences of it with a new value (if found)<br />
*'''sort''' sorts the elements in the array in ascending order<br />
*'''strinfigy''' returns a string variable that includes each array element separated by semicolons (;) <br />
<br />
'''Referencing Array Elements'''<br />
<br />
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.<br />
<br />
<pre><br />
!script {{<br />
--~dummy|array;pagetokens;myarray;@{selected|token_id}<br />
--~count|array;getcount;myarray<br />
--+Total:|There are [&count] graphical objects on the page<br />
--~testvar|array;getfirst;myarray<br />
--:loop|<br />
--+Value|[*[&testvar]:character_name]<br />
--~testvar|array;getnext;myarray<br />
--?[&testvar] -ne ArrayError|loop<br />
--+Loop1|Is Done!<br />
}}<br />
</pre><br />
<br />
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:<br />
<br />
<pre><br />
!script {{<br />
--~dummy|array;pagetokens;myarray;@{selected|token_id}<br />
--~count|array;getcount;myarray<br />
--+Total:|There are [&count] graphical objects on the page<br />
--%loopCounter|1;[&count]<br />
--+Value|[*[@myarray([&loopCounter])]:character_name]<br />
--%|<br />
--+Loop|Is Done!<br />
}}<br />
</pre><br />
<br />
This line : <nowiki>--+Value|[*[@myarray([&loopCounter])]:character_name]</nowiki> uses [@arrayName(index)] format (inside a [*characterid:attribute] syntax) to perform the same task as running through the loop with the index.<br />
<br />
(Note: Additional examples are on the way...)<br />
<br />
== For...Next Loops ==<br />
<br />
For...Next loops in ScriptCards are supported with the with the --% statement type. A loop is defined by starting off with:<br />
<br />
<pre><br />
--%LoopCounter|<start>;<end>;[step]<br />
</pre><br />
<br />
The start and end values are required, while the step parameter is optional. If the step is omitted, it will be assumed to be 1. A string variable named after the line tag ("LoopCounter" in the case above) will be created and will hold the current iteration value for the loop. Here is a real example:<br />
<br />
<pre><br />
--%LoopCounter|1;10;1<br />
</pre><br />
<br />
This will begin a loop identified by "LoopCounter" that will start at 1, increasing by 1 each iteration (the step) until it has completed 10 executions.<br />
<br />
The "next" statement is simply <code>--%|</code>, with no tag or parameters. This indicates to ScriptCards that it should increment the counter and go back to the beginning of the loop. Extending the example above:<br />
<br />
<pre><br />
!script {{<br />
--%LoopCounter|1;10;1<br />
--=Roll|1d20<br />
--+Loop|Counter is [&LoopCounter], roll was [$Roll]<br />
--%|<br />
}}<br />
</pre><br />
<br />
The <code>--%!|</code> sequence will break out of the loop, no matter how many iterations are remaining.<br />
<br />
The % and %! character sequences can also be used as part of a 1.2.1+ non-branching conditional to continue or break the loop:<br />
<br />
<pre><br />
--?"X[&RollInto]X" -eq "XX"|%<br />
</pre><br />
<br />
In this example, if the string variable RollInfo is empty, the loop will return to the top and continue with the next iteration, while:<br />
<br />
<pre><br />
--?"X[&RollInto]X" -eq "XX"|%!<br />
</pre><br />
<br />
Would cause the whole loop to end if the condition were true.<br />
<br />
== Referencing ==<br />
<br />
=== Roll Variables===<br />
<br />
Roll Variables can be referenced from the content portion of any line type, and from the tag portion of conditional statements. The referenced value is replaced when the line is executed.<br />
<br />
There are several modifiers that can be used to reference parts of a roll:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Modifier !! Meaning<br />
|-<br />
| No modifier || In a Direct Output Line (<nowiki>--+</nowiki>), GM Output Line (<nowiki>--*</nowiki>), or String Assignement (<nowiki>--&</nowiki>), 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<br />
|-<br />
| .Total || The end result of the roll equation. Formatting rules for "No Modifier" apply based on line type. <br />
|-<br />
| .Raw || The total value of the roll variable without any formatting, no matter what kind of line the reference is used in.<br />
|-<br />
| .Base || The cumulative result of any dice rolled in the Roll Text (Numeric modifiers are not included) <br />
|-<br />
| .Ones || The number of dice in the roll that came up as 1s <br />
|-<br />
| .Aces || The number of dice in the roll that came up as the maximum number on the die <br />
|-<br />
| .Odds || The number of dice in the roll that came up with an odd number <br />
|-<br />
| .Evens || The number of dice in the roll that came up with an even number <br />
|-<br />
| .RollText || The raw text of the roll that was use to generate the results <br />
|-<br />
| .Text || A text representation of the results of the roll, including the numbers rolled for each die <br />
|-<br />
| .tableEntryText || The text portion of the result of a table roll<br />
|-<br />
| .tableEntryImgURL || The image source portion of the result of a table roll<br />
|-<br />
| .tableEntryValue || If the tableEntryText is purely numeric, will contain the numeric value<br />
|}<br />
<br />
=== String Variables ===<br />
<br />
To reference a string variable, use the notation [&variablename]. String variables can be referenced in direct output, roll variable assignment, and string variable assignment statements.<br />
<br />
=== Character/Token Attributes ===<br />
<br />
A character or token attribute can be referenced from content portion of any type of line and is substituted when the line is executed. The general format for referencing a character attribute is [*ID:attribute]. ID can be a token ID or a character ID (these start with a dash). Additionally if you have specified a sourceToken or targetToken, you can substitute "S" or "T" for the ID (for example [*S:npc_type] will retrieve the npc_type attribute from the source token.<br />
<br />
By default, all attribute references will be pulled from the '''''character''''' object that the ID represents (either directly or by being a Token ID that represents a character).<br />
<br />
Keep in mind, that if you want to access the "max" of a character attribute (for example, the max hit points), then you cannot trust the name that your roll20 character sheet shows you when you hover your mouse over the max hit points. For example, this reference will not work: [*S:hp_max]. Instead, you need to use this reference: [*S:hp^].<br />
<br />
If your ID refers to a token, token attributes can be accessed by preceding the attribute name with "t-", for example [*S:t-aura1_radius]. Supported token attributes are:<br />
<br />
{|<br />
| t-name || t-id || t-statusmarkers || t-bar1_value<br />
|-<br />
| t-bar1_max || t-bar2_value || t-bar2_max || t-bar3_value<br />
|-<br />
| t-bar3_max || t-top || t-left || t-width<br />
|-<br />
| t-height || t-rotation || t-layer || t-aura1_radius<br />
|-<br />
| t-aura1_color || t-aura2_radius || t-aura2_color || t-aura1_square<br />
|-<br />
| t-aura2_square || t-tint_color || t-light_radius || t-light_dimradius<br />
|-<br />
| t-light_angle || t-light_losangle || t-light_multiplier || t-light_otherplayers<br />
|-<br />
| t-light_hassight || t-flipv || t-fliph || t-controlledby<br />
|-<br />
| t-_cardid || t-_pageid || t-imgsrc || t-bar1_link<br />
|-<br />
| t-bar2_link || t-bar3_link || t-represents || t-layer<br />
|-<br />
| t-isdrawing || t-name || t-gmnotes || t-showname<br />
|-<br />
| t-showplayers_name || t-showplayers_bar1 || t-showplayers_bar2 || t-showplayers_bar3<br />
|-<br />
| t-showplayers_aura1 || t-showplayers_aura2 || t-playersedit_name || t-playersedit_bar1<br />
|-<br />
| t-playersedit_bar2 || t-playersedit_bar3 || t-playersedit_aura1 || t-playersedit_aura2<br />
|-<br />
| t-lastmove || t-adv_fow_view_distance || t-has_bright_light_vision || t-has_night_vision<br />
|-<br />
| t-night_vision_distance || t-emits_bright_light || t-bright_light_distance || t-emits_low_light<br />
|-<br />
| t-low_light_distance || t-has_limit_field_of_vision || t-limit_field_of_vision_center || t-limit_field_of_vision_total<br />
|-<br />
| t-has_limit_field_of_night_vision || t-limit_field_of_night_vision_center || t-limit_field_of_night_vision_total || t-has_directional_bright_light<br />
|-<br />
| t-directional_bright_light_center || t-directional_bright_light_total || t-has_directional_dim_light || t-directional_dim_light_center<br />
|-<br />
| t-directional_dim_light_total || t-lightColor || || |<br />
|}<br />
<br />
'''''It is important to note that some attributes names on tokens have corresponding attribute names on characters, which represent different values. For example, [*T:id] returns the character ID, while [*T:t-id] returns the token ID.'''''<br />
<br />
=== Subroutine Parameters ===<br />
<br />
When using a gosub statement (-->) or a conditional marked as a gosub (prefixing the label with a > character), you can pass any number of parameters separated by semicolons (;) that the code in the subroutine can utilize.<br />
<br />
Subroutine parameters are numbered starting at 1, and are accessed by using the notation [%number%], so the first parameter is [%1%], the second is [%2%], etc.<br />
<br />
Parameter substitution happens on all line types, and happens prior to character attribute references or roll variable substitution.<br />
<br />
=== Campaign Attribute ===<br />
You can retrieve properties of the API's Campaign object with the [*C:attributename] syntax. For example, [*C:playerpageid] will retrieve the current player ribbon page from the Campaign object.<br />
<br />
=== Page Attributes ===<br />
If you have set the '''activepage''' parameter, you can retrieve page-related properties with the [*P:attributename] syntax, including the page's UDL parameters.<br />
<br />
=== Repeating Section Values ===<br />
<br />
You can reference repeating attribute data using the syntax [*R:attributename] syntax (similar to referencing standard character attributes). The currently active repeating row information will be used to retrieve attribute values. You can also retrieve the full attribute name for a repeating row attribute by using the [*R>attributename] notation. This is useful to pass to things like chatsetattr.<br />
<br />
=== Array Elements ===<br />
After an array has been declared, the elements can be referenced with [@arrayName(index)]. Array indices start at 0.<br />
<br />
== Deferred Resolution for Meta Scripts ==<br />
<br />
As of 1.2.9, ScriptCards supports a deferral character for use when calling another API script with via the --@ statement, to defer processing of meta script references so they get processed prior to the sub-API call insted of prior to ScriptCards execution. To defer this processing for meta script (SelectManager, Fetch) by inserting a deferral character into the meta call. For example, if I want to have ScriptCards call TokenMod as if the token for "Quej Gr'stra" (yes, I let Roll20 name my test NPCs) I could use something like this:<br />
<br />
--@token-mod|{^& select Quej Gr'stra} _on showname<br />
<br />
The "^" in between { and & will prevent SelectManager from seeing the call when the ScriptCard script is processed, but the --@ statement will remove the deferral character so the command that will be sent by ScriptCards is:<br />
<br />
!token-mod {& select Quej Gr'stra} --on showname<br />
<br />
With the deferral character removed, SelectManager will see the {& select ...} and do its magic.<br />
<br />
While the default deferral character is "^", the deferral character is a setting that can be changed:<br />
<br />
--#deferralcharacter|%<br />
<br />
Will make % the deferral character for future --@ statements in the running script.<br />
<br />
There are currently three supported Meta script structures: {^&...} for SelectManager, @^(...) and *^(...) for fetch, where the ^ in the structures here represents the placement of the deferral character.<br />
<br />
== Arrays ==<br />
<br />
Arrays are a new data type introduced in version 1.1.12 of ScriptCards, and are manipulated with associated function (--~) commands.<br />
<br />
* Arrays are a lists of strings. Items in an array cannot contain the semi-colon (;) character, as that is used to separate parameters in the function code that deals with arrays.<br />
* Arrays are accessed via the --~ script command. In some cases, the value of the tag (variable name) for array commands is not used, and can be a dummy value or simply omitted. I have omitted them in the statements below.<br />
* All commands that DO return a value return string values, even if the content is numeric.<br />
* If a command returns a value and there is some sort of reason that it isn't an array value, you will get "ArrayError" in the return value. This can happen if you reach the end of an array while stepping through it, for example, so checking for "ArrayError" can serve as the end condition for a loop.<br />
* Each array keeps track of its current index, allowing you to step forward and backwards through arrays.<br />
* Any number of arrays can be defined.<br />
* Unlike string variables and roll variables, array variables cannot (currently) be referenced directly. It is necessary to use the function (--~) syntax to manipulate arrays and get values from them as strings for use in other parts of your script.<br />
<br />
<br />
== Reentrant Scripts ==<br />
<br />
Reentrant scripts allow you to create buttons in your script code that will re-execute the script at a given label within the code. If you set the reentrant setting (--#reentrant|somevalue) to a non-zero value, your setting and variable information will be preserved between executions. Reentrant script can be used to present menus or choices and then continue acting.<br />
<br />
Reentrant buttons are created with the [rbutton]Caption::ReentryLabel;Parameter[/rbutton] construct. The caption will be displayed on the generated button. ReentryLabel is the name of a label in your script that the button will jump to when clicked, and Parameter will be passed in as a string value called "reentryval".<br />
<br />
Example:<br />
<pre><br />
!script {{<br />
--#reentrant|testing<br />
--=Roll|1d20<br />
--+Roll|[$Roll]<br />
--&String|That was a [$Roll.Raw]!<br />
--~x|array;define;MyArray;Apple;Banana;Orange<br />
--+Try it|[rbutton]Hello!::EXEC_PC_SPELL;9[/rbutton]<br />
--X|<br />
<br />
--:EXEC_PC_SPELL|<br />
--+ReentryVal|[&reentryval]<br />
--+The value of Roll is|[$Roll]<br />
--+Value of String|[&String]<br />
--+Array|[@MyArray(0)]<br />
--X|<br />
}}<br />
</pre><br />
<br />
This script sets up some variables and then displays a button labeled "Hello!". If the user clicks the button, the script will be re-entered starting at the "EXEC_PC_SPELL", which will display the content of the variables from the original execution.<br />
<br />
'''''Note: This section needs to be expanded upon'''''<br />
<br />
== Procedure Libraries ==<br />
<br />
You can now create handouts in your game in Roll 20 with the name format "ScriptCards Library NAME", where name is a name you assign to the library. Library names are case sensitive. It is my hope that the more proficient ScriptCards scripters out there will provide procedure libraries (or procedures that can be included in libraries) for others to use to make their scripting life easier. Be they specific to a game system, or to a type of activity, I think a robust set of libraries that GMs could use to enhance their scripting capabilities would be very valuable to the community. Should such things begin to emerge, I’ll create a portion of the ScriptCards Wiki page to house them.<br />
<br />
To include one or more libraries in a script, use the +++libname+++ directive (does not need a -- line associated with it). Multiple library names can be specified by separating them with semicolons (i.e., +++General;dnd5elib;Colorize+++ would include three libraries (General, dnd5elib, and Colorize).<br />
<br />
Included libraries are separated from the main script code by the automatic inclusion of "--X|" before the first library is appended to the script, and all libraries are loaded at the end of the script before script processing takes place.<br />
<br />
Procedures and labels in libraries can be used just as if they were included in the body of your script. Note that this DOES mean that you could, technically, jump into a library with a direct branch (--^) or direct branch conditional, but I recommend using libraries to store reusable procedures.<br />
The Notes section of the library handout stores the library code, and is written just like any other ScriptCards code except:<br />
<br />
* They cannot use roll queries (?{Some Prompt:}) to get information from the user at execution time.<br />
* They cannot use @{} notation to access character and token information.<br />
<br />
Both of these limitation stem from the fact that Procedure Libraries are not processed by the chat server, which is what handles these items.<br />
<br />
Here is an example of handling damage modifications (resistance, vulnerability, and immunity) in D&D 5E with a library:<br />
<br />
<pre><br />
!script {{<br />
+++dnd5elib+++<br />
--#|Damage Modifiers Test<br />
--#targettoken|@{target|token_id}<br />
-->Lib5E_CheckDamageModifiers|ResistType;fire<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] fire damage<br />
<br />
-->Lib5E_CheckDamageModifiers|ResistType;cold<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] cold damage<br />
<br />
-->Lib5E_CheckDamageModifiers|ResistType;poison<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] poison damage<br />
<br />
-->Lib5E_CheckDamageModifiers|ResistType;acid<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] acid damage<br />
<br />
--X|<br />
}}<br />
</pre><br />
<br />
Library content (In a handout called “ScriptCards Library dnd5elib” NOTE: Paste into Notepad first and then paste into the handout in Roll20 to avoid bringing over HTML formatting from the web site):<br />
<br />
<pre><br />
--/|ScriptCards Library: dnd5elib version 0.0.1<br />
--/|Provides various utility procedures for D&D 5E games<br />
<br />
--/|Lib5E_CheckDamageModifiers handle damage resistance, vulnerability, and immunity. <br />
--/|Pass a string variable to be filled with a string to be appended to a dice roll and the damage type <br />
<br />
--:Lib5E_CheckDamageModifiers|damageVariableName;damageType<br />
--&[%1%]|<br />
--?"[*T:npc_vulnerabilities]" -inc "[%2%]"|>_Lib5E_IsVulnerable;[%1%]<br />
--?"[*T:npc_resistances]" -inc "[%2%]"|>_Lib5E_IsResistant;[%1%]<br />
--?"[*T:npc_immunities]" -inc "[%2%]"|>_Lib5E_IsImmune;[%1%]<br />
--<|<br />
<br />
--:_Lib5E_IsVulnerable| --&[%1%]| * 2 [Vulnerable] --<|<br />
--:_Lib5E_IsResistant| --&[%1%]| \ 2 [Resistant] --<|<br />
--:_Lib5E_IsImmune| --&[%1%]| * 0 [Immune] --<|<br />
</pre><br />
<br />
The idea is that the functions in the library create a string that can be appended to a roll to modify the output based on resistances, so you pass Lib5E_CheckDamageModifiers the name of the string variable you want to use and the damage type. The variable (ResistType in this case) will include either nothing, “* 2 [Vulnerable]”, “\ 2 [Resistant]”, or “* 0 [Immune]” which can be included in a roll assignment (--=) to modify the damage as appropriate. The order here might be important if an NPC is misconfigured to be both resistant and immune to the same damage type. Since immune is an absolute, having it last ensures that it will override resistant or vulnerable. A creature that is both vulnerable and resistant (again, misconfigured) will come back as resistant since that condition is checked after vulnerable.<br />
Some notes: I prefix my library labels with either “Lib5E_” or “_Lib5E_” as a clarity convention. This isn’t strictly necessary but you should be aware that if two libraries (or if your script and a library) define the same label, the last label defined will win. Since libraries are appended to the end of the script in the order you include them in the +++libname+++ directive, you can somewhat control this, but it is probably best to avoid re-declaring labels. <br />
<br />
In my case, items beginning with “Lib5E_” are intended to be called by scripts, while items beginning with “_Lib5E_” are intended to be used as subroutines by the “public” procedures. Of course, there is no reason you couldn’t call them directly.<br />
<br />
You might also note that I’ve included some library information in comment lines (--/|) at the top of the library. These are ignored by ScriptCards, and are a good way to convey requirements, parameters, usage information, etc.<br />
<br />
== Example Libraries ==<br />
<br />
=== dnd5elib ===<br />
<br />
[https://github.com/kjaegers/ScriptCards Download the dnd5elib Library from the ScriptCards GitHub]<br />
<br />
The '''dnd5elib''' library provides a collection of utility procedures that help simplify dealing with the D&D 5E Official Sheet. Some of the procedures in this library require '''chatsetattr''' to be installed in your game. This is a growing library, and currently only has a handful of routines. They are:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Procedure Name !! Notes<br />
|-<br />
| style="white-space:nowrap" | Lib5E_CheckDamageModifiers || This procedure can be used to evaluate vulnerabilities, resistances, and invulnerabilities on an NPC. After setting the --#target| parameters, pass the Lib5E_CheckDamageModifiers procedure a variable name (no reference information) and a damage type (i.e., fire, cold, bludgeoning, etc.) and a string variable with the name passed in as the first parameter will be created that contains text that can be included in a roll line (--=) in order to modify the roll as appropriate. For example, '''-->Lib5E_CheckDamageModifiers|ResistType;fire''' will check the current target character's attributes for "fire" and will either return an empty string (no references), "* 0 [Immune]" if the creature is immune, "\ 2 [Resistant]" if the creature is resistant, or "* 2 [Vulnerable]" if the creature is vulnerable to fire damage.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_DeductSpellSlot || Pass in a character_id and a slot level, and the script will expend one spell slot of that level, capping the value at 0 slots remaining. For Example '''<nowiki>-->Lib5E_DeductSpellSlot|@{selected|character_id};1</nowiki>''' to deduct a first level spell slot from the selected character.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_FindResource || Used to locate a resource value on a character. Pass in a character_id, a resource name, and two variable names. The procedure will check both repeating and non-repeating resources looking for a resource whose name matches what was passed in and return three variables. The first will be a string variable named for the 3rd parameter and contains the attribute name of the resource's "name" field. The second will be a string variable named after parameter 4 and contains the resource's value field attribute name, and the third variable is a Roll Variable, also named after the 4th parameter that contains the current resource value. Example: '''<nowiki>-->Lib5E_FindResource|@{selected|character_id};Crossbow bolts;ResName;ResValue</nowiki>''' will find "Crossbow bolts" as a resource on the character and return [&ResName] which is the name of the resource attribute, [&ResValue] which is the '''name of the attribute that stores the value''' and [$ResValue] which is the current numeric value of the resource.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Global_Attack_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Attack Modifiers (repeating_tohitmod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Bless" for 1d4 active and "Being Cool" for +2 active, I will get a return string " + 1d4 [Bless] + 2 [Being Cool]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Save_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Save Modifiers (repeating_savemod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Bless" for 1d4 active and "Being Cool" for +2 active, I will get a return string " + 1d4 [Bless] + 2 [Being Cool]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Skill_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Skill Modifiers (repeating_skillmod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Guidance" for 1d4 active and "Being Cool" for +2 active, I will get a return string " + 1d4 [Guidance] + 2 [Being Cool]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_AC_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Save Modifiers (repeating_savemod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Shield of Faith" with a value of 2 active, I will get a return string " + 2 [Shield of Faith]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Damage_Modifiers || Pass a character ID and TWO string variable to set the return value. The first string will be for normal damage, and the second will be the additional damage on a crit. This procedure will look through the Global Damage Modifiers (repeating_damagemod_*) for rows that are active (checked on the character sheet) and return two strings with the dice rolls and descriptions for them (for example, if I have "Sneak Attack" with a value of 1d6 normal and 1d6 critical damage active, I will get a return string " + 1d6 [Sneak Attack]" and another string of " + 1d6 [Sneak Attack CRIT]" that can be used in a dice rolls.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_DivineSmiteDice || Used to calculate the number of dice to be rolled for a paladin's Divine Smite. Pass a target token id, a spell slot level, and a string variable to be set to the dice roll amount based on the NPC_TYPE attribute of the target token. The returned variable will contain a dice roll (like "3d8" that can be used in a --= line)<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Character_Summary || Outputs a mini character sheet, including clickable buttons for attacks, actions, legendary actions, etc. Will automatically detect a PC vs NPC and output the appropriate sections.<br />
|}<br />
<br />
Due to formatting issues with the Wiki, the library code has been moved to a [https://gist.github.com/kjaegers/52f6049ddd257f0a1288aca4bbde13c5 GITHUB GIT]. Please view the GIST in raw mode and copy the text and paste it into a handout called "ScriptCards Library dnd5elib" in your Roll20 Game.<br />
<br />
== What to Know if you are Coming from PowerCards ==<br />
<br />
''Note: This section is a work in progress.''<br />
<br />
While ScriptCards and PowerCard have very similar output goals, their internals and use are quite different. The table below summarizes some of the major differences between the scripts.<br />
<br />
::{| class="wikitable"<br />
|-<br />
! PowerCards !! ScriptCards <br />
|-<br />
| With a handful of exceptions, all lines in a PowerCard macro are intended to produce a line of output on the final card. || With ScriptCards, ONLY the <code>--+</code> and <code>--*</code> statement types produces output <br />
|-<br />
| PowerCards lines begin with two dashes (<code>--</code>) followed by a unique tag name for the line, followed by a vertical bar and the content for the line. || ScriptCards lines begin with two dashes (<code>--</code>) followed by a '''statement type identifier''', which is a single character that identifies the type of line to the interpreter. This is followed by a tag (frequently optional), a vertical bar, and the parameters for the statement being executed.<br />
|-<br />
| PowerCard macros are always processed top to bottom. Lines can be hidden so they don't output anything, but there is no looping or branching (--SkipTo looks like a branch, but it just hides all of the lines until the referenced label. || ScriptCards scripts support true branching, including direct branching (<code>--^</code>) and procedure branching (<code>--></code>) and (<code>--<</code>). Procedures support parameters and a call stack so procedures can be nested to call other procedures.<br />
|-<br />
| All lines in a PowerCards macro need to have unique tags because PowerCards builds the card as a single JavaScript object using the tag names to store what will be displayed. This is why repeated tag names always result in the last one being shown. || ScriptCards tags do not need to be unique, and in the case of many line types are optional.<br />
|-<br />
| PowerCards conditionals result in either showing or hiding the line they are on. || ScriptCards conditionals '''''only''''' support branching as the result of the comparison. This branching can be direct (a GOTO) or procedural (a GOSUB) '''''NOTE: As of version 1.2.0, ScriptCards also supports roll/string variable assignment as a result of conditional evaluation'''''<br />
|-<br />
| PowerCards relies on the Roll20 [[Quantum Roll]] server and inline rolls for all dice functions || ScriptCards includes its own dice roll parser, and '''''does not support''''' inline rolls.<br />
|-<br />
| PowerCards RollIDs (often mistaken for variables) are assigned by analyzing the results of an inline roll, and cannot be referenced in other rolls, so you can't roll a <code>1d4</code> and then roll a <code>1d20</code> and add the <code>1d4</code> result because all of the rolls happen on the chat server before PowerCards gets the macro text. || ScriptCards supports two types of variables: Roll Variables and String Variables. Because ScriptCards uses its own roll parser and is not dependent upon the chat server, rolls and their results can be used in other rolls, math functions, output, etc.<br />
|}<br />
<br />
== Example Scripts ==<br />
<br />
Below are some sample scripts that utilize the various statement types in ScriptCards:<br />
<br />
=== Divine Smite ===<br />
<br />
This script will prompt the user for a spell slot level to expend on a divine smite. It will check the target's npc_type to see if it is an Undead or Fiend, which adds an additional d8 to the smite roll.<br />
<br />
[[File:ScriptCards Divine Smite.png|Divine Smite Script Output]]<br />
<br />
<pre><br />
!scriptcard {{<br />
--#title|Divine Smite<br />
--=DiceCount|?{Spell Slot Level?|1|2|3|4|5|6|7|8|9} + 1<br />
--=IsFiendOrUndead|0<br />
--?"@{target|npc_type}" -inc fiend|>IsBoosted<br />
--?"@{target|npc_type}" -inc undead|>IsBoosted<br />
--=TotalDice|[$DiceCount] + [$IsFiendOrUndead]<br />
--=SmiteRoll|[$TotalDice]d8<br />
--#emoteText|@{selected|token_name} smites @{target|token_name}<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
--+Smite|deals [$SmiteRoll] radiant damage.<br />
--X|<br />
<br />
--:IsBoosted|<br />
--=IsFiendOrUndead|1<br />
--<|<br />
}}<br />
</pre><br />
<br />
==== How It Works ====<br />
<br />
The first line sets the "title" card parameter to "Divine Smite".<br />
<br />
Line 2 Shows a query to the user asking for the spell slot level, adds one and stores the value in the "DiceCount" Roll Variable. The query/dropdown is generated by the chat server prior to the script being executed.<br />
<br />
Line 3 defaults the "IsFiendOrUndead" Roll Variable to 0.<br />
<br />
Lines 4 and 5 compare the target's "npc_type" attribute (passed by the chat server as text) to see if they include either "undead" or "fiend". If true, the IsBoosted subroutine will be called. No parameters are passed to this subroutine.<br />
<br />
Line 6 sets the "TotalDice" variable to the base (DiceCount) number plus the IsFiendOrUndead number, which will be a 0 or a 1.<br />
<br />
Line 7 calculates "SmiteRoll" by rolling a number of d8 equal to the "TotalDice" value.<br />
<br />
Lines 8-10 set the parameters for the emote, which appears above the card content. By setting the sourceToken and the targetToken, their icons will appear in the emote surrounding the text describing the action.<br />
<br />
Line 11 is the only line that actually produces output on the card. It results in "Smite deals # radiant damage".<br />
<br />
Line 12 ends the script execution, preventing the script from continuing and running the subroutines out of context.<br />
<br />
Lines 14-16 are the IsBoosted subroutine, starting with the :IsBoosted label. The IsFiendOrUndead variable is set to 1, and a return from subroutine is executed.<br />
<br />
=== Magic Missile ===<br />
<br />
This script demonstrates using a loop and calling a subroutine to fire a number of missiles determine by the spell slot level used to cast the spell.<br />
<br />
[[File:ScriptCards_MagicMissile_Fixed.png|Magic Missile Script Output]]<br />
<br />
<pre><br />
!scriptcard {{ <br />
--#title|Magic Missile<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
--=MissileCount|?{Spell Slot Level?|1|2|3|4|5|6|7|8|9} + 2<br />
--=DisplayCount|1<br />
--=MissileDamage|0<br />
--#leftsub|Slot level ?{Spell Slot Level?}<br />
--#rightsub|Ranged Attack<br />
--#emoteText|Fred uses a level ?{Spell Slot Level?} spell slot to fire [$MissileCount.Total] missiles of magical force!<br />
--:MissileLoop|<br />
-->FireMissile|<br />
--=DisplayCount|[$DisplayCount] + 1<br />
--?[$DisplayCount] -le [$MissileCount]|MissileLoop<br />
--+Total|Total damage is [$MissileDamage]<br />
--X|<br />
<br />
--:FireMissile|<br />
--=ThisMissile|1d4 + 1<br />
--=MissileDamage|[$MissileDamage] + [$ThisMissile]<br />
--+Missile|[$DisplayCount.Total] Hits for [$ThisMissile] [b]force[/b] damage<br />
--<|<br />
}}<br />
</pre><br />
<br />
==== How It Works ====<br />
<br />
Lines 1-3 set the card title, the source token and the target token. Setting these tokens causes their icons/avatars to appear in the Emote section of the card.<br />
<br />
Line 4 asks the user what spell slot level they wish to use to cast magic missile. The number of missiles fired is equal to 2 plus the spell level, and this is stored in the MissileCount variable.<br />
<br />
Line 5 stores a 1 in the DisplayCount variable. This will be used to control the loop to determine the number of missiles fired and the missile number when displaying damage rolls.<br />
<br />
Line 6 initializes MissileDamage to 0<br />
<br />
Line 7 sets the left subtitle to the text "Slot Level #", where # is the spell slot level being used.<br />
<br />
Line 8 sets the right subtitle to the text "Ranged Attack".<br />
<br />
Line 9 sets the emoteText parameter with a description of the action, including the slot level and number of missiles fired.<br />
<br />
Line 10 is a label for the missile firing loop<br />
<br />
Line 11 Calls the "FireMissile" subroutine<br />
<br />
Line 12 increases the DisplayCount variable by 1<br />
<br />
Line 13 Checks to see if there are still missles to fire (DisplayCount <= MissileCount) and if so branches to MissileLoop<br />
<br />
Line 14 Displays the total damage dealt by the spell.<br />
<br />
Line 15 stops execution of the script to prevent out of context execution of the subroutine.<br />
<br />
Lines 76-21 are the FireMissile subroutine, beginning with the FireMissile label. The 1d4+1 is rolled and assigned to "ThisMissile". The result is added to the existing MissileDamage total, and a line for the current missile is displayed with the missile number and the damage for the missile.<br />
<br />
=== Longsword Attack ===<br />
<br />
This script demonstrates a standard 5E D&D melee weapon attack, including detection of misses, fumbles, hits, and critical hits. If installed, alterbars is used to decrement the target's BAR3 value by the damage dealt.<br />
<br />
[[File:ScriptCards Longsword.png|Longsword Script Output]]<br />
<br />
<pre><br />
!scriptcard {{<br />
--#title|Longsword<br />
--#leftsub|Melee Attack<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
--#emoteText|@{selected|token_name} attacks @{target|token_name}<br />
--=TargetAC|@{target|npc_ac}<br />
--?[$TargetAC.Total] -gt 0|DoneWithAC<br />
--=TargetAC|@{target|ac}<br />
--:DoneWithAC|<br />
--=AttackRoll|1d20 + @{selected|strength_mod} [STR] + @{selected|pb} [PROF]<br />
--+Attack|@{selected|token_name} rolls [$AttackRoll] vs AC [$TargetAC].<br />
--?[$AttackRoll.Base] -eq 20|Crit<br />
--?[$AttackRoll.Base] -eq 1|Fumble<br />
--?[$AttackRoll.Total] -ge [$TargetAC.Total]|Hit<br />
--+Miss|The attack missed.<br />
--^Final|<br />
<br />
--:Fumble|<br />
--+Fumble!|The attack went horribly wrong.<br />
--^Final|<br />
<br />
--:Hit|<br />
--=Damage|1d8 + @{selected|strength_mod} [STR]<br />
--+Hit!|The attack hit @{target|token_name} for [$Damage] slashing damage.<br />
--@alter|_target|@{target|token_id} _bar|3 _amount|-[$Damage]<br />
--^Final|<br />
<br />
--:Crit|<br />
--=Damage|1d8 + @{selected|strength_mod} [STR] + 1d8 [CRIT]<br />
--+Critical Hit!|The attack hit @{target|token_name} for [$Damage] slashing damage.<br />
--@alter|_target|@{target|token_id} _bar|3 _amount|-[$Damage]<br />
<br />
--:Final|<br />
}}<br />
</pre><br />
<br />
==== How it Works ====<br />
<br />
In lines 1-5, we set the title, subtitle, and emote text along with the tokens for the emote area.<br />
<br />
Lines 6-9 allow us to determine the AC of the target. On the 5E Roll20 sheet, NPCs armor class is stored in "npc_ac", while PCs armor class is in "ac". First we grab npc_ac and if it is zero, we check AC.<br />
<br />
Line 10 rolls the attack roll, rolling 1d20 and adding the attacker's strength modifier and proficiency bonus<br />
<br />
Line 11 displays the result of the attack roll on the card<br />
<br />
Lines 12-14 determine what kind of result the attack had. If the .Base value of the roll was 20, we branch to "Crit". If it was 1, we branch to "Fumble". If the .Total value of the roll was greater than or equal to the AC that was determined in Lines 6-9, we branch to Hit.<br />
<br />
Assuming we didn't branc anywhere, the result of the attack was a miss, so we display that on line 15 and then branch to "Final"<br />
<br />
This is followed by three branch segments, :Fumble, :Hit, and :Crit. A fumble displays a text message and branches to :Final.<br />
<br />
On a hit or a crit, we roll Damage (adding additional damage dice on a crit). We display a "Hit!" or "Critical Hit!" message and then make an API call to AlterBars, passing it the token id, bar we want to modify (3 in this case), and the amount we want to modify by the Damage value.<br />
<br />
=== Party Health Status ===<br />
<br />
This example calculates the current Hit Points remaining and HP percentage for each character and creates a color-coded display with the current party status.<br />
<br />
[[File:ScriptCards Party Health.png]]<br />
<br />
<pre><br />
!scriptcard {{<br />
--#title|Party Status<br />
--#titleCardBackground|#33CC33<br />
--#oddrowbackground|#bfee90<br />
--#evenrowbackground|#90eebf<br />
-->HealthCheck|@{Quej Grastra|character_id}<br />
-->HealthCheck|@{Brim Cheuto|character_id}<br />
-->HealthCheck|@{Odug Ututees|character_id}<br />
--X|End of card Execution<br />
<br />
--:HealthCheck|<br />
--=HealthPerc|[*[%1%]:hp] / [*[%1%]:hp^] * 100 \ 1<br />
--=HealthColor|000000<br />
--?[$HealthPerc.Total] -gt 50|HealthSkip<br />
--=HealthColor|FF0000<br />
--:HealthSkip|<br />
--+[*[%1%]:character_name]|has [#[$HealthColor.RollText]][*[%1%]:hp] of [*[%1%]:hp^][/#] HP [R]([$HealthPerc.Total]%)[/R]<br />
--<|End of HealthCheck<br />
}}<br />
</pre><br />
<br />
==== How it Works ====<br />
<br />
Lines 1-4, we set the card title, and set the title background and row background colors to shades of green.<br />
<br />
Lines 5-7 make gosub calls the the "HealthCheck" subroutine, passing in the character ID of each of the named characters (these are the names of the characters in my test game)<br />
<br />
Line 8 terminates the script execution.<br />
<br />
The remaining lines of the script are the HealthCheck subroutine, which works like this:<br />
<br />
Line 10 is the subroutine label (:HealthCheck)<br />
<br />
Line 11 uses the character id passed as a parameter and combines it with character attribute lookup *(...) to retrieve the value of "hp" and "hp<nowiki>^</nowiki>" for the character. The <nowiki>^</nowiki> character is used to specify that we want the MAX value for this attribute for the second call. We divide these two numbers and multiple by 100 to get a percentage. Finally, we use integer division by 1 to round the percentage and drop the decimals. The end result gets stored in the HealthPerc roll variable.<br />
<br />
Line 12 defaults to color of the health text to black<br />
<br />
Line 13 check to see if the health percentage is greater than 50. If so, it branches to HealthSkip, preventing the script from executing line 13.<br />
<br />
Line 14 sets the color of the health text to red<br />
<br />
Line 15 is the label that will be branched to from Line 13 to skip the red coloring<br />
<br />
Line 16 again uses character attribute substitution and the passed parameter value to output a display line containing the character name, the colorized health total, and the percentage value. The percentage is right-justified.<br />
<br />
Line 17 returns from the HealthCheck subroutine.<br />
<br />
=== Expanded Magic Missile Script ===<br />
<br />
This is the expanded and enhanced version of the Magic Missile script covered in {{yt|watch?v=u50xvNzS9Zk | this video}}. It includes visual and audio effects, checking and deducting spell slots, and applying damage using either Token-Mod or Alterbars.<br />
<br />
<pre><br />
!scriptcard {{ <br />
--#title|Magic Missile<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
<br />
-->GetAndCheckSlotInformation|<br />
<br />
--=MissileCount|[$SlotLevel] + 2<br />
--=DisplayCount|1<br />
--=MissileDamage|0<br />
--#leftsub|Slot level [$SlotLevel]<br />
--#rightsub|Ranged Attack<br />
--#emoteText|@{selected|character_name} uses a level [$SlotLevel.Total] spell slot to fire [$MissileCount.Total] missiles of magical force!<br />
<br />
--:MissileLoop|<br />
-->FireMissile|<br />
--=DisplayCount|[$DisplayCount] + 1<br />
--?[$DisplayCount] -le [$MissileCount]|MissileLoop<br />
--+Total|Total damage is [$MissileDamage]<br />
-->DeductSpellSlot|<br />
--#rightsub|Level [$SlotLevel] Left: [$SlotsRemaining] <br />
-->PlayEffects|none;burst-smoke;beam-magic;spell_01<br />
-->ApplyDamageTokenmod|@{target|token_id};3;-[$MissileDamage]<br />
-->ApplyDamageAlterbars|@{target|token_id};3;-[$MissileDamage]<br />
--X|<br />
<br />
--:FireMissile|<br />
--=ThisMissile|1d4 + 1<br />
--=MissileDamage|[$MissileDamage] + [$ThisMissile]<br />
--+Missile|[$DisplayCount.Total] Hits for [$ThisMissile] [b]force[/b] damage<br />
--<|<br />
<br />
--:GetAndCheckSlotInformation|<br />
--=SlotLevel|?{Spell Slot Level?|1|2|3|4|5|6|7|8|9}<br />
--=SlotsTotal|[*S:lvl[$SlotLevel]_slots_total]<br />
--=SlotsExpended|[*S:lvl[$SlotLevel]_slots_expended]<br />
--?[$SlotsExpended.Total] -ge [$SlotsTotal.Total]|NoSlotsLeft<br />
--<|<br />
<br />
--:NoSlotsLeft|<br />
--+|[*S:character_name] has no level [$SlotLevel.Total] spell slots available.<br />
--X|<br />
<br />
--:DeductSpellSlot|<br />
--=SlotsExpended|[$SlotsExpended] + 1<br />
--@setattr|_charid [*S:character_id] _lvl[$SlotLevel]_slots_expended|[$SlotsExpended] _silent<br />
--=SlotsRemaining|[$SlotsTotal] - [$SlotsExpended]<br />
--<|<br />
<br />
--:PlayEffects|Parameters are : source effect; target effect; line effect; sound effect<br />
--vtoken|@{selected|token_id} [%1%]<br />
--vtoken|@{target|token_id} [%2%]<br />
--vbetweentokens|@{selected|token_id} @{target|token_id} [%3%]<br />
--@roll20AM|_audio,play,nomenu|[%4%]<br />
--<|<br />
<br />
--:ApplyDamageTokenmod|Parameters are tokenid;bar#;amount<br />
--@token-mod|_ignore-selected _ids [%1%] _set bar[%2%]_value|[%3%]<br />
--<|<br />
<br />
--:ApplyDamageAlterbars|<br />
--@alter|_target|[%1%] _bar|[%2%] _amount|[%3%]<br />
--<|<br />
}}<br />
</pre><br />
<br />
[[Category:Featured articles]]</div>5004103https://wiki.roll20.net/Script:ScriptCardsScript:ScriptCards2021-09-28T17:04:45Z<p>5004103: /* Comment (--/) */</p>
<hr />
<div>{{revdate}}<br />
== Introduction ==<br />
'''ScriptCards''' provides a script interpreter that can be used to create powerful macros that display the results of player/NPC actions, or display other information in a pleasing visual format in your game's chat window. The scripting language contains variables (both dice-roll (enhanced numerics) and strings) as well, conditionals, branching, subroutines with parameters, and a set of built-in functions to simplify working with Roll20 information.<br />
{{script overview<br />
|name=ScriptCards<br />
|author={{user profile|2365448|Kurt J.}}<br />
|code=<br />
|version=1.4.0e<br />
|lastmodified=2021-09-24}}<br />
ScriptCards is not game-system specific, and can be used with any system/sheet. Near the end of this Wiki there is a section set aside for libraries that can implement system-specific tasks, with the hope that enthusiasts playing particular systems will create and share utility functions that can be utilized by the wider community.<br />
<br />
The default display style for ScriptCards output is similar to the format used to document player and NPC abilities in Dungeons and Dragons 4th Edition, but does not have any system ties to D&D4E.<br />
<br />
Current OneClick Version : 1.4.0e<br />
<br />
Current Development Version : 1.4.4<br />
<br />
'''''<big>Critically Important: ScriptCards does not use/parse inline rolls. ScriptCards includes its own built-in dice roll parser to allow for the use of variables inside dice rolls. As of version 1.2.3, ScriptCards will now take inline rolls and substitute the total result value in statement strings, meaning that you can utilize inline rolls but ScriptCards will only see the result of the roll, and not parse the roll components itself.</big>'''''<br />
<br />
* {{fpl|9752053/ ScriptCards thread}}<br />
** {{fpl|10000297/ Scritpcard API Working and Sharing}}<br />
* https://github.com/kjaegers/ScriptCards/tree/main/ScriptCards_API - GitHub repository for source before the one-click version is updated.<br />
* {{yt.be|hyR7Jnq4mQM ScriptCards Intro}} 45min, Jan 2021<br />
* {{yt.be|u50xvNzS9Zk ScriptCards Magic Missile Deep Dive}} 39min, Feb 2021<br />
<br />
<br />
__TOC__<br />
=== Is ScriptCards Related to [[PowerCards]]? ===<br />
<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
Check the '''[[#What to Know if you are Coming from PowerCards|What to Know if you are Coming from PowerCards]]'''-section for a comparison table between the two scripts.<br />
<br />
== What is a ScriptCard Script ==<br />
<br />
A ScriptCard Script is text written into the chat window (either typed directly, pasted, or run via a macro) that will produce a card of information in the [[text Chat|chat window]]. A ScriptCard Script is composed of an [[API]] command: <code><nowiki>!scriptcard {{ }}</nowiki></code> enclosing any number of lines that determine the output that will be added to the card. At it simplest, the following macro:<br />
<br />
<pre>!scriptcard {{ }}</pre><br />
<br />
Will produce just a title card that displays “ScriptCards” as the name:<br />
<br />
[[File:Scriptcard blank.png]]<br />
<br />
Of course, this is just the simplest type of macro and isn’t very useful. In order to produce useful output, we need to include lines between the <code><nowiki>{{</nowiki></code> and <code><nowiki>}}</nowiki></code> that direct the API script as to what it should do.<br />
<br />
== Structure of a ScriptCard Line ==<br />
<br />
All ScriptCard lines begin with two dashes, followed by an ''statement identifier character'' that lets ScriptCards what type of line it is. There are several of these, and they are detailed in the next section. After the line type identifier, a Tag name 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.<br />
<br />
Following the Tag is a vertical bar, and then the content of the line itself. Again, each type of line might interpret this content differently.<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Identifier !! Statement Type !! Tag !! Content !! Notes<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--/</nowiki> || Comment || unused || unused || The <code>--/</code> 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--#</nowiki> || 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").<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--+</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--=</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--&</nowiki> || Assign String 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. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--@</nowiki> || 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 (i.e., [[TokenMod|!token-mod]], or [[ChatSetAttr|!setattr]], etc.)<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--:</nowiki> || 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<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--^</nowiki> || Branch To || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--></nowiki> || Call Procedure || 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<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--<</nowiki> || 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.<br />
|- <br />
| style="white-space:nowrap" | <nowiki>--?</nowiki> || Conditional Branch || Condition to be evaluated || True Branch Label<nowiki>|</nowiki>False Branch Label || The condition will be evaluated and execution will jump to one of the two indicated branches (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 included a semicolon separated list of parameters. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--s</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--l</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--v</nowiki> || 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+'''''<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--e</nowiki> || Echo to Chat || Name to send chat command as || Chat message to send || Variable substitution takes place on the tag and content.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--R</nowiki> || Retrieve Repeating Section Row information || "find", "first", or "next" || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--~</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--c</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--i</nowiki> || Information Request || User Prompt;Button Caption || InfoType;VariableName;ParameterText || See full documentation below.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--d</nowiki> || 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. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--%</nowiki> || 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. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--*</nowiki> || 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.<br />
|}<br />
<br />
== ScriptCard Statement Type Details ==<br />
The sections below detail the individual statement types supported by ScriptCards<br />
<br />
=== Comment (--/) ===<br />
<br />
A --/ statement is ignored by the ScriptCards parser. You can use this type of statement to add comments and informational text to your script. <br />
<br />
Example:<br />
<pre><br />
!script {{<br />
--/|Script Name : Fireball<br />
--/|Purpose : Allow the player to cast a fireball and blow stuff up!<br />
.<br />
.<br />
.<br />
}}<br />
</pre><br />
<br />
Using the style here below will sometimes work, but it's not recommended, because it can lead to unwanted text appearing on your output card. It is better to always put the "--/|" symbol in front of every line of commenting.<br />
<pre><br />
!script {{<br />
--/|When you have a very<br />
long comment, then<br />
you sometimes have<br />
to put it in multiple<br />
lines.<br />
.<br />
.<br />
.<br />
}}<br />
</pre><br />
<br />
=== Set Parameter (--#) ===<br />
<br />
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.<br />
<br />
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.<br />
<br />
'''''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.'''''<br />
<br />
Examples:<br />
<pre><br />
--#title|Magic Missile<br />
--#leftsub|Level 1 Spell<br />
--#rightsub|Force Damage<br />
</pre><br />
<br />
The three examples above set the “title”, “leftsub”, and “rightsub” values for the card to the content value for the line. <br />
<br />
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.<br />
Settings Lines do not produce output lines on the card.<br />
<br />
The following settings are available (note that parameter names are ''not'' case sensitive):<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Name !! Effect/Use !! Default Value !! Type<br />
|-<br />
| 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<br />
|-<br />
| allowplaintextinrolls || If set to a non-zero value, plain character text in rolls will be copied to the roll text || 0 || Per-Line<br />
|-<br />
| bodyFontFace || Name of the font used in the card rows || Helvetica || Global<br />
|-<br />
| bodyFontSize || Size of the text in the card rows || 14px || Global<br />
|-<br />
| bodybackgroundimage || Specify an image (content for a CSS background-image tag) for the body area || none || Global<br />
|-<br />
| buttonBackground || Background color for buttons created with [button][/button] || #1C6EA4 || Per-Line<br />
|-<br />
| buttonBorderColor || Border (outline) color for buttons created with [button][/button] || #999999 || Per-Line<br />
|-<br />
| buttonFontFace || Font Family specifier for captions on buttons created with [button][/button] || Tahoma || Per-Line<br />
|-<br />
| buttonFontSize|| Text size for captions on buttons created with [button][/button] || x-small || Per-Line<br />
|-<br />
| buttonTextColor|| Text color of labels on buttons created with [button][/button] || #FFFFFF || Per-Line<br />
|-<br />
| 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<br />
|-<br />
| deferralcharacter || Changes the meta script deferral sequence to the specified value || ^ || Per-Line<br />
|-<br />
| diceFontColor|| Color of the dice created with the [d4] [d6], etc. formatting markers || #1C6EA4 || Per-Line<br />
|-<br />
| dicefontsize || Size of the dice created with the [d4] [d6], etc. formatting markers || 3.0em || Per-Line<br />
|-<br />
| 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<br />
|-<br />
| disablerollprocessing || If set to a non-zero value, --= lines will not process dice rolls strings || 0 || Per-Line<br />
|-<br />
| emoteBackground || Background color of the emote area || #f5f5ba || Global<br />
|-<br />
| emoteFont || Name of the font used in emote area (above the title of the output card) || Georgia || Global<br />
|-<br />
| emoteFontColor || Color of the font in the emote area || None (Empty) || Global<br />
|-<br />
| emoteFontSize || Size of the font used in the emote area || 14px || Global<br />
|-<br />
| emoteFontWeight || Font weight for the font in the emote area || bold|| Global<br />
|-<br />
| emoteState || If set to anything other than "visible", the emote portion of the card will not be displayed || visible || Global<br />
|-<br />
| emoteText || Text to display in the emote portion of the card || None (Empty) || Global<br />
|-<br />
| emotefont || Name of the font used in the emote text area || font-family: Georgia, serif; font-weight: bold; || Global<br />
|-<br />
| evenRowBackground || Hex code for the background color for even rows || #eeeeee || Per-Line<br />
|-<br />
| evenRowFontColor || Hex code for the text color for even rows || #000000 || Per-Line<br />
|-<br />
| evenrowbackgroundimage || Specify an image (content for a CSS background-image tag) for the even card rows || none || Per-Line<br />
|-<br />
| executionlimit || Maximum number of script lines the interpreter will try to execute. This prevents "infinite loop" sandbox crashes || 40000 || Global<br />
|-<br />
| hideCard || If set to any non-default value, the entire card output will be suppressed || 0 || Global<br />
|-<br />
| 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<br />
|-<br />
| 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<br />
|-<br />
| lineheight || Vertical size of each line on the output card || normal || Per-Line<br />
|-<br />
| nominmaxhighlight || If set to anything other than "0", rolls will not display crit/fumble/mixed highlight colors. || 0 || Per-Line<br />
|-<br />
| norollhighlight || If set to anything other than "0", rolls will not be formatted (plain numbers) but will still get a tooltip with details ('''''v1.3.6b+''''') || 0 || Per-Line<br />
|-<br />
| oddRowBackground || Hex code for the background color for even rows || #d0e4f5 || Per-Line <br />
|-<br />
| oddRowFontColor || Hex code for the text color for odd rows || #000000 || Per-Line<br />
|-<br />
| oddrowbackgroundimage || Specify an image (content for a CSS background-image tag) for the odd crd rows || none || Per-Line<br />
|-<br />
| reentrant || Used to name a script for rentrant button use || 0 || Global<br />
|-<br />
| 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)0 || Global<br />
|-<br />
| rollhilightlineheight || Determines the height of the hilight box placed around roll results ('''''1.4.2+''''') || 1.0em || Per-Line<br />
|-<br />
| roundUp || If set to a non-default value, integer division will round up instead of down || 0 || Per-Line<br />
|-<br />
| showfromfornonwhispers || If set to a non-zero value, will include the sender on cards that aren't whispered || 0 || Global<br />
|-<br />
| 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<br />
|-<br />
| subtitleFontColor || Color of the text in the subtitle areas || #FFFFFF || Global<br />
|-<br />
| subtitleFontFace || Name of the font used on the subtitle sections || Tahoma || Global<br />
|-<br />
| subtitleFontSize || Size of the subtitle font || 13px || Global<br />
|-<br />
| subtitleSeperator || The character(s) that will be placed between leftsub and rightsub || <nowiki>&#x2666</nowiki>; || Global<br />
|-<br />
| tableBorderRadius || CSS specifier for how rounded the borders of the output card are. Use "0px;" for square borders || 6px; || Global<br />
|-<br />
| tableShadow || CSS specifier for the drop shadow under the output card || 5px 3px 3px 0px #aaa; || Global<br />
|-<br />
| tablebgcolor || Background color of the whole card. '''''Normally not visible''''' || #EEEEEE || Global<br />
|-<br />
| tableborder || Color of the border that surrounds the whole card || 2px solid #000000; || Global<br />
|-<br />
| 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<br />
|-<br />
| timezone || IANA Specifier for the local time zone, used in system/date functions || merica/New_York || Per-Line<br />
|-<br />
| title || Text displayed in the title area of the card || ScriptCards || Global<br />
|-<br />
| titleCardBackground || A hex color code representing the background color of the title area. || #1c6ea4 || Global<br />
|-<br />
| titleFontColor || Color of the text on the card title || #FFFFFF || Global<br />
|-<br />
| titleFontFace || Name of the font used on the title area || Contrail One || Global<br />
|-<br />
| titleFontLineHeight || Line spacing on the title area || 1.2em || Global<br />
|-<br />
| titleFontSize || Size of the title font || 1.2em || Global<br />
|-<br />
| titlecardbackgroundimage || Specify an image (content for a CSS background-image tag) for the title card area || none || Global<br />
|-<br />
| titlecardbottomborder || Border CSS specifier for the bottom of the title card area || 2px solid #444444; || Global<br />
|-<br />
| titlecardgradient || If set to non-zero value, will place a vertical gradient on the title card area || 0 || Global<br />
|-<br />
| usehollowdice || If set to a non-zero value, the hollow/outline versions of the dice fonts will be used || 0 || Per-Line<br />
|-<br />
| whisper|| Comma separated list of who to whisper the output to. Use "gm" for [[GM|GMs]] and "self" for the sender || none || Global|}<br />
|}<br />
<br />
''Setting Lines do not produce output lines on the card''<br />
<br />
=== Direct Output (--+) ===<br />
<br />
A direct output line display 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.<br />
<br />
Examples of Direct Output lines:<br />
<pre><br />
--+Hello|World<br />
--+Attack|The monster rolls [$Attack] to hit!<br />
--+Damage|@{target|token_name} is hit for [$Damage] [#3333AA][b]frost[/b][/#] damage.<br />
</pre><br />
<br />
Direct Output lines support inline formatting, roll variable replacement, character attribute references, and procedure variables.<br />
<br />
=== GM Output (--*) ===<br />
<br />
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. <br />
<br />
Example:<br />
<pre><br />
--+PlayerLine|This line is shown on the public card<br />
--*GMLine|This line will only be shown to GMs, on a separate card.<br />
</pre><br />
<br />
=== Roll Variable Assignment (--=) ===<br />
<br />
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.<br />
<br />
'''''All components of a roll equation should be separated with spaces.'''''<br />
<br />
Examples:<br />
<pre><br />
--=MissileDamage|1d4 + 1<br />
--=Attack|1d20 + @{selected|strength_mod} [STR] + @{selected|pb} [PROF]<br />
</pre><br />
<br />
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. Text enclosed in square brackets ([]) is considered "flavor text" and will be added to the result text but does not impact the roll result.<br />
<br />
The following dice formats are supported:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Format Pattern !! Example !! Description<br />
|-<br />
| XdY || 3d8 || Simple format. Roll a Y-sided die X times<br />
|-<br />
| XdYkhZ || 2d20kh1 || Roll Y-sided die X times and keep the highest Z number of dice<br />
|-<br />
| XdYklZ || 4d6kl3 || Roll Y-sided die X times and keep the lowest Z number of dice <br />
|-<br />
| XdY>Z || 5d6>3 || Roll Y-sided die X times and count a 1 for each roll greater than Z <br />
|-<br />
| XdY<Z || 5d6<3 || Roll Y-sided die X times and count a 1 for each roll less than Z <br />
|}<br />
<br />
'''''Note: The dice formulae below are supported in the development version of ScriptCards and will be merged with the table above when activated on OneClick'''''<br />
::{| class="wikitable"<br />
|-<br />
! Format Pattern !! Example !! Description<br />
|-<br />
| 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<br />
|-<br />
| 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<br />
|-<br />
| 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)<br />
|-<br />
| 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<br />
|}<br />
<br />
The following operators are supported in a roll equation:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Operator !! Operation<br />
|-<br />
| + || Addition <br />
|-<br />
| - || Subtraction <br />
|-<br />
| * || Multiplication <br />
|-<br />
| / || Division <br />
|-<br />
| \ || Integer Division (Rounds down) <br />
|-<br />
| % || Modulo (Remainder of Divison)<br />
|}<br />
<br />
Roll Variables can be accessed at any time after they have been created by using the [$VariableName] format, with the following optional modifiers:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Modifier !! Meaning<br />
|-<br />
| No modifier || In a Direct Output Line (<nowiki>--+</nowiki>) 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<br />
|-<br />
| .Total || The end result of the roll equation as an unformatted number <br />
|-<br />
| .Base || The cumulative result of any dice rolled in the Roll Text (Numeric modifiers are not included) <br />
|-<br />
| .Ones || The number of dice in the roll that came up as 1s <br />
|-<br />
| .Aces || The number of dice in the roll that came up as the maximum number on the die <br />
|-<br />
| .Odds || The number of dice in the roll that came up with an odd number <br />
|-<br />
| .Evens || The number of dice in the roll that came up with an even number <br />
|-<br />
| .RollText || The raw text of the roll that was use to generate the results <br />
|-<br />
| .Text || A text representation of the results of the roll, including the numbers rolled for each die <br />
|-<br />
| .tableEntryText || The text portion of the result of a table roll<br />
|-<br />
| .tableEntryImgURL || The image source portion of the result of a table roll<br />
|-<br />
| .tableEntryValue || Numeric value of tableEntryText (via parseInt). If a non-numeric value, will be 0<br />
|-<br />
| .Raw || The total numeric result without any formatting, even if placed somewhere formatting would normally be done. <br />
|}<br />
<br />
Examples:<br />
<pre><br />
--+Total Damage|[$MissileDamage.Total] (roll was 1d4+1)<br />
--+Base Damage|[$MissileDamage.Base] (without the +1)<br />
--=Attack|1d20 + @{selected|strength_mod} [STR] + @{selected|pb} [PROF] + [$BlessBonus] [Bless]<br />
</pre><br />
<br />
In this case, 1d4 will be rolled and stored in “BlessBonus”, which can then be used in the Attack line.<br />
<br />
'''''Mathematical Functions in Roll Expressions '''''<br />
<br />
The ScriptCards roll parser works from left to right, always maintaining a current value and applying whatever comes next to the total. The following in-line functions to the roll parser. These are:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Expression !! Meaning<br />
|-<br />
| {ABS} || Absolute Value<br />
|-<br />
| {CEIL} || Ceiling value (round up to the next whole number)<br />
|-<br />
| {FLOOR} || Floor value (round down to the next whole number)<br />
|-<br />
| {ROUND} || Round value (round up if the decimal portion is greater than 0.5, otherwise round down)<br />
|-<br />
| {NEGATE} || Multiply the value by negative one.<br />
|-<br />
| {SQRT} || Take the square root of the running value. ('''''1.4.1+''''')<br />
|-<br />
| {SQUARE} || Square the running value. ('''''1.4.2+''''')<br />
|-<br />
| {CUBEROOT} || Take the cube root of the running value. ('''''1.4.2+''''')<br />
|-<br />
| {CUBE} || Cube the running value. ('''''1.4.2+''''')<br />
|-<br />
| {SIN} || Return the SIN of running value. ('''''1.4.2+''''')<br />
|-<br />
| {COS} || Return the COS of running value. ('''''1.4.2+''''')<br />
|-<br />
| {TAN} || Return the TAN of running value. ('''''1.4.2+''''')<br />
|-<br />
| {ASIN} || Return the ASIN of running value. ('''''1.4.2+''''')<br />
|-<br />
| {ACOS} || Return the ACOS of running value. ('''''1.4.2+''''')<br />
|-<br />
| {ATAN} || Return the ATAN of running value. ('''''1.4.2+''''')<br />
|}<br />
<br />
<br />
'''''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 <nowiki>[[ ]]</nowiki> 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.<br />
<br />
'''''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.<br />
<br />
'''Rolling on Rollable Tables'''<br />
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.<br />
<br />
''Roll Variable Lines do not produce output lines on the card.''<br />
<br />
=== String Variable Assignment (--&) ===<br />
<br />
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:<br />
<br />
<pre><br />
--&MyText|Hello<br />
</pre><br />
<br />
Here, we assign the text "Hello" to the string variable named MyText. You can also append text to a string variable by prefixing the content with a + sign:<br />
<br />
<pre><br />
--&MyText|+ World<br />
</pre><br />
<br />
If run after the statement above, MyText will now contain "Hello World".<br />
<br />
String variables can be referenced using the syntax [&variablename]<br />
<br />
=== Call API (--@) ===<br />
<br />
ScriptCards can use a Call API instruction to execute other API commands. The Tag contains the API 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 API command is executed.<br />
<br />
Examples:<br />
<pre><br />
--@eh|list<br />
--@alter|_target|@{target|token_id} _bar|3 _amount|-[$Damage]<br />
</pre><br />
<br />
In the first example above, the command <code>!eh list</code> will be executed, calling [[EncounterHelper]]. In the second, {{fpl|1216260/ AlterBars}} is called to modify a token's Bar 3 value.<br />
<br />
'''''Note:''''' When ScriptCards (or any API script) runs other API 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).<br />
<br />
See [[API:Script Index]] for more options.<br />
<br />
=== Branch Label (--:) ===<br />
<br />
A branch label defines a line in your code that can be reached by one of the branching instructions (<nowiki>--^</nowiki>, <nowiki>--></nowiki>, or <nowiki>--?</nowiki>). The Tag serves as the label name, and must be unique on the card.<br />
<br />
The vertical bar (|) separator must be present, but the content portion of the line is unused and can be treated as a comment.<br />
<br />
Examples:<br />
<pre><br />
--:MyLoop|<br />
--:CriticalHit|Will jump here if we roll a critical hit!<br />
</pre><br />
<br />
''A Branch Label line does not produce an output line on the card.''<br />
<br />
=== Branch (--^) === <br />
<br />
A Branch line 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.<br />
<br />
Examples:<br />
<pre><br />
--^MyLoop|Jumps to MyLoop<br />
--^SkipCrit|We didn't crit, so skip the Crit code<br />
</pre><br />
<br />
''A Branch line does not produce an output line on the card.''<br />
<br />
=== Call Procedure (-->) ===<br />
<br />
Similar to a branch, a Call Procedure (sometimes knows 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 (<nowiki>--<</nowiki>) 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 (;).<br />
<br />
Examples:<br />
<pre><br />
-->FixFormat|#3333FF;#999999<br />
</pre><br />
<br />
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%].<br />
<br />
=== Return (--<) ===<br />
<br />
A return instruction marks the end of a Gosub procedure. 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.<br />
<br />
Examples:<br />
<pre><br />
--<|<br />
--<|End of MySub<br />
</pre><br />
<br />
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.<br />
<br />
=== Conditional Statement (--?) ===<br />
<br />
A conditional statement contains some equation in the Tag that will be evaluated. '''''If any part of the comparison can/does contain a space, it needs to be surrounded by double quotes'''''<br />
<br />
Based on the true/false result of the evaluation, one of two execution paths will be taken. These execution paths are detailed in the content section of the statement. The "if true" path is specified first (directly after the vertical bar), and the "if false" path is specified after it, also separated by a vertical bar.<br />
<br />
Example:<br />
<pre><br />
--?[$AttackRoll.Total] -ge [$TargetAC]|Hit|Miss<br />
</pre><br />
<br />
'''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.'''<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Branch Format !! Meaning<br />
|-<br />
| Label || If just a label is specified, execution will branch to that label when the comparison is matched.<br />
|-<br />
| >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 <br />
|-<br />
| =VariableName || The roll variable "VariableName" will be assigned the value following a semicolon (ex: --?1 -eq 1|=Roll;1d20)<br />
|-<br />
| &VariableName || The string variable "VariableName" will be assigned the value following a semicolon (ex: --?1 -eq 1|&Result;Hit|&Result;Miss)<br />
|-<br />
| % or %! || The current for...next loop will perform the "next" action (%) or will break out (%!) <br />
|-<br />
| [ || Code block (see below)<br />
|}<br />
<br />
Examples:<br />
<pre><br />
--?[$AttackRoll.Base] -eq 20|CriticalHit<br />
--?[$AttackRoll.Base] -eq 1|>Fumble;@{selected|dexterity_mod}<br />
--?"@{target|npc_type}" -inc "undead"|&MonsterType;Undead|&MonsterType;Not Undead<br />
--?[$Attack.Total] >= [$ArmorClass]|>Hit|>Miss<br />
</pre><br />
<br />
In the first example, if the Base value of AttackRoll is a 20 (natural 20 on the die) execution will branch to the CriticalHit label.<br />
<br />
In the second example, 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%].<br />
<br />
The third example looks for the word "undead" in the npc_type attribute of the targeted character. If it exists in the text, the MonsterType string variable will be set to "Undead", otherwise it will be set to "Not Undead". <br />
<br />
The final example would call 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.<br />
<br />
''Text that does/may contain a space should be enclosed in double quotes.''<br />
<br />
The following comparison operators are available:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Comparator !! Meaning<br />
|-<br />
| -eq || Equal To <br />
|-<br />
| -eqi || Case insensitive Equal To <br />
|-<br />
| -ne || Not Equal To <br />
|-<br />
| -nei || Case insensitive Not Equal To <br />
|-<br />
| -gt || Greater Than <br />
|-<br />
| -ge || Greater Than or Equal To <br />
|-<br />
| -lt || Less Than <br />
|-<br />
| -le || Less Than or Equal To <br />
|-<br />
| -inc || Includes (text strings). <br />
|-<br />
| -ninc || Does Not Include (text strings). <br />
|}<br />
<br />
Multi-part conditionals are supported with -and and -or as separators. For example:<br />
<br />
<pre><br />
--?[$Attack.Total] -ge @{target|npc_ac} -and [$Attack.Base] -ne 20|HitButNotCrit<br />
</pre><br />
<br />
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):<br />
<br />
true AND false OR true<br />
<br />
Will be evaluated as true. The first two (true and false) will be false, but then false OR true will be true.<br />
<br />
Conversely:<br />
<br />
true or false and false<br />
<br />
Will be false, because the first true and false will evaluate to true, and then true and false will be false.<br />
<br />
'''CODE BLOCKS'''<br />
<br />
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.<br />
<br />
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:<br />
<br />
<pre><br />
!script {{<br />
--=Roll|1d2<br />
--+Roll|[$Roll]<br />
--?[$Roll.Total] -eq 2|[<br />
--&Value|Yep!<br />
--+|We are inside the TRUE portion of the block<br />
--]|[<br />
--&Value|Nope<br />
--+|We are inside the FALSE portion of the block<br />
--]|<br />
--+After|the blocks!<br />
--+Value|[&Value]<br />
}}<br />
</pre><br />
<br />
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 --]|. <br />
<br />
At this time, blocks cannot be nested, and can only be created as part of a conditional (--[ is not a valid statement type)<br />
<br />
''A conditional statement does not produce a line of output on the card.''<br />
<br />
=== Case Statement (--c) ===<br />
<br />
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 (:). Each match condition includes a branch label that will be used if the test value matches the item. 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:<br />
<br />
<pre><br />
!script {{<br />
--#title|Case Statement Testing<br />
--=Roll|1d4<br />
--C[$Roll.Total]|1:>One;[$Roll]|2:>Two;[$Roll]|3:>Three;[$Roll]|4:>Four;[$Roll]<br />
--X|<br />
<br />
--:One| --+Value|was One ([%1%]) --<|<br />
--:Two| --+Value|was Two ([%1%]) --<|<br />
--:Three| --+Value|was Three ([%1%]) --<|<br />
--:Four| --+Value|was Four ([%1%]) --<|<br />
}}<br />
</pre><br />
<br />
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 variable as a parameter.<br />
<br />
=== Save and Load (--s and --l) ===<br />
<br />
This statement pair is used to either store (--s) or load (--l) data from persistent storage. Items stored in persistent storage remain between card rolls and between Roll20 sessions. There are two types of data that can be stored: settings and roll variables. <br />
<br />
Examples:<br />
<br />
<pre><br />
--Ssettings|GreenStyle<br />
--Srollvariables|FirstCardVars<br />
</pre><br />
<br />
In this case, the tag for the statement determines what type of item is being saved (settings or rollvariables). When saving settings, all non-default settings are written to the named setting storage value. When Roll Variables are saved, all variables that currently exist will be saved to the named storage value.<br />
<br />
Loading stored items simply requires the same command with the --l statement type:<br />
<br />
<pre><br />
--Lsettings|GreenStyle<br />
--Lrollvariables|FirstCardVars<br />
</pre><br />
<br />
When loading settings, all stored settings will be applied to the current card settings. You can override settings by changing them after the load.<br />
<br />
When loading roll variables, the saved variables will be added to (or overwrite if they have the same name) any variables on the current card. This means it is safe to create roll variables before the load statement.<br />
<br />
'''Practical Uses'''<br />
The major intended use of persistent storage is for storing card formats for use in later scripts. For example, the following script:<br />
<br />
<pre><br />
!scriptcard {{<br />
--#titlecardbackground|#22CC22<br />
--#oddrowbackground|#cceecc<br />
--#evenrowbackground|#99ee99<br />
--Ssettings|@{selected|token_name}<br />
}}<br />
</pre><br />
<br />
Would save the titlecardbackground, oddrowbackground, and evenrowbackground settings to a saved list named after the selected token's name. When creating cards for that token to run later, you could include the line:<br />
<br />
<pre><br />
--Lsettings|@{selected|token_name}<br />
</pre><br />
<br />
To load all of the settings at once. By creating these setting sets for each character, you can specify a different color scheme for each character that can then be used in cards with a single formatting line.<br />
<br />
There is a supplemental ! command added to support saved settings:<br />
<br />
<pre><br />
!sc-liststoredsettings<br />
</pre><br />
<br />
Will produce a list of all stored setting names, with buttons to list the setting values stored in each group and a button to delete groups as needed.<br />
<br />
=== Visual Effects (--v) ===<br />
<br />
The --v statement can be used to create visual effects on the tabletop. The tag portion of the statement can be either "token" or "betweentokens". The content portion of the statement contains the required parameters for the effect generation, separated by spaces. If the effect is "none", no effect will be played. If any other value that doesn't match a Roll20 effect name will result in a burst-fire effect.<br />
<br />
For "token" effects, the parameters are the token id for the token the effect happens on, followed by the effect specifier.<br />
<br />
Example:<br />
<pre><br />
--vtoken|@{selected|token_id} burst-fire<br />
</pre><br />
<br />
For "betweentoken" effects, the parameters are the source token id, the target token id, and the effect specifier.<br />
<br />
Example:<br />
<pre><br />
--vbetweentokens|@{selected|token_id} @{target|token_id} beam-magic<br />
</pre><br />
<br />
'''''Version 1.2.8+'''''<br />
<br />
An additional effect specifier, "point" is available in 1.2.8+. This specifier allows you to create a visual effect at a designated X/Y pixel coordinate. Future updates will add custom-vfx support to this option. The parameters are the X and Y coordinates and the effect descriptor. As of version 1.2.9, you can also use custom effect specifiers with Point effects:<br />
<br />
<pre><br />
--vpoint|150 200 burst-fire<br />
</pre><br />
<br />
=== Echo to Chat (--e) ===<br />
<br />
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.<br />
<br />
Example:<br />
<pre><br />
--eThe Ghost|/em hovers around @{selected|character_name}... BOO!<br />
</pre><br />
<br />
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).<br />
<br />
'''''Whispering'''''<br />
<br />
You can use the echo statement to send a whisper, but there's a trick to it. If you execute this code here:<br />
<br />
<pre><br />
--eThe Ghost|/w ExamplePlayerName Boo.<br />
</pre><br />
<br />
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.<br />
<br />
So, in conclusion, it's best to use something like this when you're sending a whisper:<br />
<br />
<pre><br />
!script {{<br />
--#hidecard|1<br />
--&sender|The Ghost<br />
--&receiver|ExamplePlayerName<br />
--&message|Boo.<br />
--e[&sender]|/w [&receiver] [&message]<br />
--eScriptCards|/w gm **Whispered from [&sender] to [&receiver]:** [&message] <br />
}}<br />
</pre><br />
<br />
This will ensure that the message appears in your chat feed as well.<br />
<br />
=== Repeating Section Access (--R) ===<br />
<br />
ScriptCards (as of v0.0.13) supports accessing repeating section rows on a character sheet with the --R statement type. <br />
<br />
There are three basic commands you can use with --R, and they are specified by the tag used:<br />
<br />
<pre><br />
--Rfind|characterid;EntryName;SectionPrefix;SearchField<br />
</pre><br />
<br />
This is the most direct way to access a repeating section row. Supplying the character ID, followed by what you are looking for (Greatsword, for example), followed by the character sheet's section prefix (repeating_attack), followed by the field to check what you are searching for (atkname) will load the matching section (if found) into the script parsers memory. For example:<br />
<br />
<pre><br />
--Rfind|@{selected|character_id};Greatsword;repeating_attack;atkname<br />
</pre><br />
<br />
Will look at the character's "repeating_attack" section for an entry with an atkname value equal to "Greatsword". Similarly:<br />
<br />
<pre><br />
--Rfind|@{selected|character_id};Bite;repeating_npcaction;name<br />
</pre><br />
<br />
Will look for a "Bite" action on an NPC's action list.<br />
<br />
<pre><br />
--Rfirst|characterid;section prefix<br />
</pre><br />
<br />
This form of the --R command will look at all of the entries in the specified repeating section and load the first one into memory:<br />
<br />
<pre><br />
--Rfirst|@{selected|character_id};repeating_attack<br />
</pre><br />
<br />
Would load the character's first "repeating_attack" row into memory.<br />
<br />
<pre><br />
--Rnext|<br />
</pre><br />
<br />
No parameters are required for --Rnext, which loads the next entry in the list that was obtained with "first" into memory.<br />
<br />
However a row is obtained, it will be parsed to replace any attribute references (ie, @{level}) with the corresponding character attribute.<br />
<br />
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".<br />
<br />
You can reference repeating attribute data using the syntax [*R:attributename] syntax (similar to referencing standard character attributes).<br />
<br />
Here are some examples:<br />
<br />
Display the details of the "Greatsword" PC attack:<br />
<br />
<pre><br />
!script {{<br />
--Rfind|@{selected|character_id};Greatsword;repeating_attack;atkname<br />
--+Attack Name|[*R:atkname]<br />
--+Base Damage|[*R:dmgbase]<br />
}}<br />
</pre><br />
<br />
[[File:Scriptcards repeating greatsword.png|Repeating Greatsword Attack]]<br />
<br />
List all of the actions an NPC can take (just actions, not legendary, etc.)<br />
<br />
<pre><br />
!script {{<br />
--#title|NPC Actions<br />
--#leftsub|@{selected|token_name}<br />
--Rfirst|@{selected|character_id};repeating_npcaction<br />
--:DisplayLoop|<br />
--?"[*R:name]" -eq NoRepeatingAttributeLoaded|Done<br />
--+Action:|[*R:name] [*R:attack_damage] [*R:attack_damagetype]<br />
--?"[*R:attack_damage2]" -eq ""|NoSecondaryDamage<br />
--+ |[*R:attack_damage2] [*R:attack_damagetype2]<br />
--:NoSecondaryDamage|<br />
--Rnext|<br />
-->DisplayLoop| <br />
--:Done|<br />
}}<br />
</pre><br />
<br />
[[File:Scriptcards repeating npcactions.png]]<br />
<br />
In the script above, we get the "first" repeating_npcaction and display information about it. We then execute "next" and repeat until we run into "NoRepeatingAttributeLoaded".<br />
<br />
'''''Special debugging command: dump'''''<br />
<pre><br />
--Rdump|<br />
</pre><br />
<br />
The "dump" command will list all of the attributes ScriptCards knows about for the currently loaded repeating row to the API Console Log.<br />
<br />
=== Assign Variable to Built-In Function (--~) ===<br />
<br />
ScriptCards has the ability to run a function built into the API script and return the results to a variable. Some functions return roll variables, while others return strings. See the function table below for details. The format is:<br />
<br />
--~VariableName|function;param1;param2;param3;...<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Function Name !! Parameters !! Description<br />
|-<br />
| distance || token_A_ID;token_B_ID || Calculate the Chebyshev distance in grid units between two tokens. This is the measurement scheme D&D 4E/5E use for diagonal distance measurement<br />
|-<br />
| euclideandistance || token_A_ID;token_B_ID || Calculate the Euclidean distance between two tokens. This is essentially the Pythagorean theorem in action. Returns the result in grid units.<br />
|-<br />
| euclideanpixel || token_A_ID;token_B_ID || Calculate the Euclidean distance between two tokens and returns the result is pixels instead of grid units. <br />
|-<br />
| euclideanlong || token_A_ID;token_B_ID || 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 is calculated instead of before. More accurate over long distances. <br />
|-<br />
| manhattandistance || token_A_ID;token_B_ID || Also called "taxicabdistance" (which is an acceptable function name), this measures to how-many-over, how-many-up/down distance, disallowing diagonal movement.<br />
|-<br />
| getselected || none || 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 the first selected token, VariableName2 the second, etc.<br />
|}<br />
<br />
'''''Functions with Sub Functions'''''<br />
<br />
Most ScriptCards functions are grouped into set as sub functions. The table below lists the major functions and their sub functions.<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Function Name !! Sub Function !! Parameters !! Return Type !! Description<br />
|-<br />
| array || define || arrayname;value1;value2;... || none || Creates an array called "arrayname" and adds value1, value2, etc. to the array<br />
|-<br />
| array || sort || arrayname || none || Sorts the specified array in place in ascending order<br />
|-<br />
| array || add || arrayname;value1;value2;... || none || Adds value1, value2, ... to the existing array "arrayname"<br />
|-<br />
| array || remove || arrayname;value1;value2;... || none || Removes value1, value2, ... from the existing array "arrayname". Resets the array index to 0.<br />
|-<br />
| array || replace || arrayname;currentvalue;newvalue || none || Replaces all occurrences of "currentvalue" in "arayname" with "newvalue"<br />
|-<br />
| array || setatindex || arrayname;index;newvalue || none || Replaces the array item at index "index" with "newvalue"<br />
|-<br />
| array || getindex || arrayname || stringVariable || Retrieves the current index in "arrayname" and stores it in the supplied string variable<br />
|-<br />
| array || setindex || arrayname;newindex || none || Sets the current index in array "arrayname" to "newindex"<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| array || removeat || arrayname;indexposition || none || Removes the item at index "indexposition" from "arrayname". Resets the current array index to 0.<br />
|-<br />
| array || indexof || arrayname;searchvalue || stringVariable || Searches the array "arrayname" for and item with the value of "searchvalue" and, if found, returns the index of the first matching value or "ArrayError" if not found<br />
|-<br />
| array || getlength || arrayname || stringVariable || Returns the number of items in array "arrayname"<br />
|-<br />
| array || pagetokens || arrayname;tokenid;(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. 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.)<br />
|-<br />
| 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.<br />
|-<br />
| array || stringify || arrayname || stringVariable || Returns all of the items in "arrayname" as a string separated by semicolons (;)<br />
|-<br />
| array || fromstring || arrayname || delimiter;string || Creates an array from "string", splitting "string" on "delimiter" to separate the items<br />
|-<br />
| array || statusmarkers|| arrayname;tokenid || none|| Creates an array (arrayname) of the active statusmarkers (sometimes called Token Markers) for the specified tokenid<br />
|-<br />
| math || angle || math;angle;tokenid;tokenid|| rollVariable || Calculates the angle between two tokens and returns the value in degrees<br />
|-<br />
| math || ceil || math;ceil;value || rollVariable || Rounds '''value''' up to the next integer, dropping any decimal portion of the number<br />
|-<br />
| math || clamp || math;clamp;value;lowerBound;upperBound || rollVariable || Returns '''value''', but restricted to the range of '''loweBound''' and '''upperBound'''.<br />
|-<br />
| math || floor || math;floor;value || rollVariable || Rounds '''value''' down, dropping any decimal portion of the number<br />
|-<br />
| math || max || math;max;valueA;valueB || rollVariable || Returns the larger of '''valueA''' vs '''valueB'''<br />
|-<br />
| math || min || math;min;valueA;valueB || rollVariable || Returns the smaller of '''valueA''' vs '''valueB'''<br />
|-<br />
| math || round || math;round;value || rollVariable || Rounds '''value''' to the nearest integer<br />
|-<br />
| string || length || string;length;stringValue || rollVariable || Returns the length of '''stringValue''' in characters<br />
|-<br />
| string || before || string;before;searchText;stringValue || stringVariable || Searches '''stringValue''' for '''searchText''' and returns the portion of '''stringValue''' prior to that text<br />
|-<br />
| string || after || string;after;searchText;stringValue || stringVariable || Searches '''stringValue''' for '''searchText''' and returns the portion of '''stringValue''' after that text<br />
|-<br />
| string || left || string;left;count;stringValue || stringVariable || Returns the leftmost '''count''' characters of '''stringValue'''<br />
|-<br />
| string || right || string;right;count;stringValue || stringVariable || Returns the rightmost '''count''' characters of '''stringValue'''<br />
|-<br />
| string || replace || string;replace;searchText;replaceText;stringValue || stringVariable || Replaces '''searchText''' in '''stringValue''' with '''replaceText''' and returns the resulting string<br />
|-<br />
| string || replaceall || string;replace;searchText;replaceText;stringValue || stringVariable || Replaces all intances of '''searchText''' in '''stringValue''' with '''replaceText''' and returns the resulting string '''''Requires 1.2.9+'''''<br />
|-<br />
| string || trim || string;trim;stringValue || stringVariable || Removes leading and trailing spaces from stringValue and returns the result. <br />
|-<br />
| string || substring || string;substring;start;count;stringValue || stringVariable || Returns '''count''' characters starting at '''start''' from '''stringValue'''<br />
|-<br />
| 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.<br />
|-<br />
| string || tolowercase || string;tolowercase;stringValue || stringVariable || Converts the passed string to lower case and assigns to the passed variable name. <br />
|-<br />
| string || touppercase || string || stringVariable || Converts the passed string to upper case and assigns to the passed variable name. <br />
|-<br />
| 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. <br />
|-<br />
| 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.<br />
|-<br />
| 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'''.<br />
|-<br />
| turnorder || clear || none || none || Clears all entries from the {{Turn Tracker}}/Initiative<br />
|-<br />
| turnorder || addtoken || tokenid;trackervalue || none || Adds the token represented by "tokenid" to the initiative tracker with an initiavie value of "trackervalue"<br />
|-<br />
| turnorder || replacetoken || tokenid;trackervalue || none || Replaces the token represented by "tokenid" in the initiative tracker with an initiavie value of "trackervalue". Will add the token if it doesn't exist in the tracker.<br />
|-<br />
| turnorder || removetoken || tokenid || none || Removes the token represented by "tokenid" from the initiative tracker if it exists<br />
|-<br />
| turnorder || addcustom || textlabel;trackervalue || none || Add a custom text entry to the {{Turn Tracker}}/Initiative named "textlabel" with an initiative value of "trackervalue"<br />
|-<br />
| system || date || getdatetime || stringVariable || Returns the date time in the active timezone (see settings) <br />
|-<br />
| system || date || getdate || stringVariable || Returns the date in the active timezone (see settings) <br />
|-<br />
| system || date || gettime || stringVariable || Returns the time in the active timezone (see settings)<br />
|-<br />
| system || dumpvariables || "rolls", "string", or "array" || none || Dumps all of the defined variables of the indicated type to the console log<br />
|-<br />
| system || findability || system;findability;charactername;abilityname || stringVariable || Returns the object ID of the ability on the indicated character or "AbilityNotFound"<br />
|-<br />
|}<br />
<br />
Examples:<br />
<br />
<pre><br />
--~HowFarAway|distance;@{selected|token_id};@{target|token_id}<br />
</pre><br />
<br />
Returns the distance (Chebyshev) between the selected and target tokens and stores it in "HowFarAway".<br />
<br />
<pre><br />
--SelectedDudes|getselected<br />
</pre><br />
<br />
If 5 tokens were selected, 6 variables would be created: SelectedDudesCount (with a value of 5), SelectedDudes1, SelectedDudes2, SelectedDudes3, SelectedDudes4, SelectedDudes5.<br />
<br />
=== Information Request (--i) ===<br />
<br />
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.<br />
<br />
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.<br />
<br />
After the user has clicked the button and responded to the requests, ScriptCards will resume processing the script from where it left off.<br />
<br />
Here is an example “i” line:<br />
<br />
<pre><br />
--IScriptCards needs additional information to continue;Click to select a target and provide information|t;MyNewTarget;Missile1Target||q;MyNameIs;What is your name?<br />
</pre><br />
<br />
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.<br />
<br />
Supported information request types are “t” for target token, and “q” for query.<br />
<br />
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).<br />
<br />
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:<br />
<br />
<pre><br />
q;UserName;What is your name?|Fred|Bob|Sally|Nancy<br />
</pre><br />
<br />
Would have a dropdown menu with four choices.<br />
<br />
== Inline Formatting ==<br />
<br />
Inline formatting is processed on Direct Output lines only (--+ lines) and the following inline format markup is available:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Formatting Tags !! Description<br />
|-<br />
| [b]..[/b] || Bold the text between the markers <br />
|-<br />
| [i]..[/i] || Italicize the text between the markers <br />
|-<br />
| [u]..[/u] || Underline the text between the markers <br />
|-<br />
| [s]..[/s] || Strike-Thru the text between the markers <br />
|-<br />
| [c]..[/c] || Center alignment <br />
|-<br />
| [l]..[/l] || Left alignment <br />
|-<br />
| [r]..[/r] || Right alignment <br />
|-<br />
| [j]..[/j] || Full justification alignment <br />
|-<br />
| [#xxx]..[/#] or [#xxxxxx]..[/#] || Use a 3 or 6 digit hex code to colorize the text between the markers <br />
|-<br />
| [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, <code>[img width=128 height=128]</code> )<br />
|-<br />
| [button]caption::action[/button] || Create a button with the label "caption" that performs the action defined by "action". <br />
|-<br />
| [t] || Converted to HTML table tag. Text after the "t" will be included inside the tag (width, border, etc)<br />
|-<br />
| [/t] || Converted to HTML close table tag.<br />
|-<br />
| [tr] || Converted to HTML table row tag. Text after the "tr" will be included inside the tag<br />
|-<br />
| [/tr] || Converted to HTML close table row tag.<br />
|-<br />
| [td] || Converted to HTML table cell tag. Text after the "tr" will be included inside the tag<br />
|-<br />
| [/td] || Converted to HTML close table cell tag.<br />
|}<br />
<br />
== Variables ==<br />
<br />
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. While it is possible to assign both a string and a roll variable the same name, doing so will likely result in confusion when looking at the script later, so it is not recommended.<br />
<br />
String Variables are assigned with the --& statement and are referenced using [&variableName] notation.<br />
<br />
Roll Variables are assigned with the --= statement, and the assignment value is always processed by the ScriptCards Roll Processor (resolves dice rolls, etc.)<br />
<br />
There are a handful of variables assigned automatically when a ScriptCard is executed. These are all string variables, and are:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Variable !! Value<br />
|-<br />
| SendingPlayerID || Contains the object ID of the player that sent the macro<br />
|-<br />
| SendingPlayerName || Contains the display name of the player<br />
|-<br />
| SendingPlayerColor || Contains the color code associated with the player<br />
|-<br />
| SendingPlayerSpeakingAs || The contents of the "Speaking As" dropdown window<br />
|-<br />
| SendingPlayerIsGM || Contains 1 if the player is a GM, and 0 if the player is NOT a GM<br />
|}<br />
<br />
== Arrays ==<br />
<br />
Arrays are a special type of variable, and are managed by the function (<nowiki>--~</nowiki> command). All of the array function commands follow the same pattern:<br />
<br />
<pre>--~variableName|array;subcommand;arrayname;param1;param2;param3;...</pre><br />
<br />
Not all array commands return anything to "variableName". The function table above will specify the return type of the command if any.<br />
<br />
There are a couple of different ways to create an array:<br />
<br />
The '''define''' array subcommand creates (or recreates) an array and assigns it values - one for each included parameter after the array name. For example:<br />
<br />
<pre>--~|array;define;Fruits;mango;peach;strawberry;apricot;banana;apple</pre><br />
<br />
will create an array called '''Fruits''' with 6 elements in the order listed in the command (mango, peach, etc.)<br />
<br />
You can also use two other subcommands to create arrays based on tokens:<br />
<br />
<pre>--~Count|array;pagetokens;Everybondy;@{selected|token_id}</pre><br />
<br />
and<br />
<br />
<pre>--~Count|array;selectedtokens;Selected</pre><br />
<br />
In both cases, arrays of tokens will be created, and a string variable called "Count" will be set to the number of tokens in the array. The '''pagetokens''' command returns (by default) all of the tokens on the page that contains the token passed as the parameter after the array name. You can filter the tokens that "pagetokens" includes in the array by appending an optional parameter describing the type of token you are looking for:<br />
<br />
<pre>--~Count|array;pagetokens;Everybondy;@{selected|token_id};npc</pre><br />
<br />
Will return only tokens on the page that represent characters that do not have a ''controlledby'' parameter set. The available options are "all" (default), "char", "graphic", "pc", and "npc".<br />
<br />
The '''selectedtokens''' command returns an array with all of the tokens that were selected when the script was called.<br />
<br />
You can also use an arbitrary string to create an array, specifying a delimiter with the '''fromstring''' command:<br />
<br />
<pre><br />
--&names|Fred<br />
--&names|+,Sally<br />
--&names|+,Ted<br />
--&names|+,Joyce<br />
--~|array;fromstring;,;[&names]<br />
</pre><br />
<br />
The above example builds a comma-separated string and then uses "fromstring" to create an array with 4 elements from it, specifying the comma as the delimiter.<br />
<br />
Finally, you can use the '''statusmarkers''' command to create an array with one entry for each active status marker on a specified token:<br />
<br />
<pre>--~|array;statusmarkers;Conditions;@{selected|token_id}</pre><br />
<br />
will create an array with one entry for each status active on the selected token. The array elements will be the internal name of the status (if you are using custom status marker packs, the names will be specified in the marker pack).<br />
<br />
'''Traversing Arrays'''<br />
<br />
Each array keeps track of an internal index position (starting at 0). Several commands let you manage this index:<br />
<br />
*'''getindex''' returns the current index value<br />
*'''setindex''' sets the index to the specified location in the array<br />
*'''getlength''' returns the number of elements in the array<br />
*'''indexof''' returns the index location of the specified element<br />
<br />
Other commands let you retrieve values from the array:<br />
<br />
*'''getfirst''' sets the index to 0 and returns the value at that position<br />
*'''getnext''' advances the index by 1 and returns the new current value<br />
*'''getprevious''' reduces the index by 1 and returns the new current value<br />
*'''getlast''' sets the index to the last elements in the array and returns the new current value<br />
<br />
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.<br />
<br />
'''Manipulating Array Elements'''<br />
<br />
Several array commands deal with inserting, removing, and modifying elements:<br />
<br />
*'''add''' works just like define, except that it takes an existing array and adds elements to it based on the passed parameters<br />
*'''remove''' looks for items matching each passed parameter and removes them from the indicated array if they exist<br />
*'''removeat''' allows you to specify an index location in the array and remove the element at that position<br />
*'''replace''' searches an array for a value and replaces all occurrences of it with a new value (if found)<br />
*'''sort''' sorts the elements in the array in ascending order<br />
*'''strinfigy''' returns a string variable that includes each array element separated by semicolons (;) <br />
<br />
'''Referencing Array Elements'''<br />
<br />
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.<br />
<br />
<pre><br />
!script {{<br />
--~dummy|array;pagetokens;myarray;@{selected|token_id}<br />
--~count|array;getcount;myarray<br />
--+Total:|There are [&count] graphical objects on the page<br />
--~testvar|array;getfirst;myarray<br />
--:loop|<br />
--+Value|[*[&testvar]:character_name]<br />
--~testvar|array;getnext;myarray<br />
--?[&testvar] -ne ArrayError|loop<br />
--+Loop1|Is Done!<br />
}}<br />
</pre><br />
<br />
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:<br />
<br />
<pre><br />
!script {{<br />
--~dummy|array;pagetokens;myarray;@{selected|token_id}<br />
--~count|array;getcount;myarray<br />
--+Total:|There are [&count] graphical objects on the page<br />
--%loopCounter|1;[&count]<br />
--+Value|[*[@myarray([&loopCounter])]:character_name]<br />
--%|<br />
--+Loop|Is Done!<br />
}}<br />
</pre><br />
<br />
This line : <nowiki>--+Value|[*[@myarray([&loopCounter])]:character_name]</nowiki> uses [@arrayName(index)] format (inside a [*characterid:attribute] syntax) to perform the same task as running through the loop with the index.<br />
<br />
(Note: Additional examples are on the way...)<br />
<br />
== For...Next Loops ==<br />
<br />
For...Next loops in ScriptCards are supported with the with the --% statement type. A loop is defined by starting off with:<br />
<br />
<pre><br />
--%LoopCounter|<start>;<end>;[step]<br />
</pre><br />
<br />
The start and end values are required, while the step parameter is optional. If the step is omitted, it will be assumed to be 1. A string variable named after the line tag ("LoopCounter" in the case above) will be created and will hold the current iteration value for the loop. Here is a real example:<br />
<br />
<pre><br />
--%LoopCounter|1;10;1<br />
</pre><br />
<br />
This will begin a loop identified by "LoopCounter" that will start at 1, increasing by 1 each iteration (the step) until it has completed 10 executions.<br />
<br />
The "next" statement is simply <code>--%|</code>, with no tag or parameters. This indicates to ScriptCards that it should increment the counter and go back to the beginning of the loop. Extending the example above:<br />
<br />
<pre><br />
!script {{<br />
--%LoopCounter|1;10;1<br />
--=Roll|1d20<br />
--+Loop|Counter is [&LoopCounter], roll was [$Roll]<br />
--%|<br />
}}<br />
</pre><br />
<br />
The <code>--%!|</code> sequence will break out of the loop, no matter how many iterations are remaining.<br />
<br />
The % and %! character sequences can also be used as part of a 1.2.1+ non-branching conditional to continue or break the loop:<br />
<br />
<pre><br />
--?"X[&RollInto]X" -eq "XX"|%<br />
</pre><br />
<br />
In this example, if the string variable RollInfo is empty, the loop will return to the top and continue with the next iteration, while:<br />
<br />
<pre><br />
--?"X[&RollInto]X" -eq "XX"|%!<br />
</pre><br />
<br />
Would cause the whole loop to end if the condition were true.<br />
<br />
== Referencing ==<br />
<br />
=== Roll Variables===<br />
<br />
Roll Variables can be referenced from the content portion of any line type, and from the tag portion of conditional statements. The referenced value is replaced when the line is executed.<br />
<br />
There are several modifiers that can be used to reference parts of a roll:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Modifier !! Meaning<br />
|-<br />
| No modifier || In a Direct Output Line (<nowiki>--+</nowiki>), GM Output Line (<nowiki>--*</nowiki>), or String Assignement (<nowiki>--&</nowiki>), 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<br />
|-<br />
| .Total || The end result of the roll equation. Formatting rules for "No Modifier" apply based on line type. <br />
|-<br />
| .Raw || The total value of the roll variable without any formatting, no matter what kind of line the reference is used in.<br />
|-<br />
| .Base || The cumulative result of any dice rolled in the Roll Text (Numeric modifiers are not included) <br />
|-<br />
| .Ones || The number of dice in the roll that came up as 1s <br />
|-<br />
| .Aces || The number of dice in the roll that came up as the maximum number on the die <br />
|-<br />
| .Odds || The number of dice in the roll that came up with an odd number <br />
|-<br />
| .Evens || The number of dice in the roll that came up with an even number <br />
|-<br />
| .RollText || The raw text of the roll that was use to generate the results <br />
|-<br />
| .Text || A text representation of the results of the roll, including the numbers rolled for each die <br />
|-<br />
| .tableEntryText || The text portion of the result of a table roll<br />
|-<br />
| .tableEntryImgURL || The image source portion of the result of a table roll<br />
|-<br />
| .tableEntryValue || If the tableEntryText is purely numeric, will contain the numeric value<br />
|}<br />
<br />
=== String Variables ===<br />
<br />
To reference a string variable, use the notation [&variablename]. String variables can be referenced in direct output, roll variable assignment, and string variable assignment statements.<br />
<br />
=== Character/Token Attributes ===<br />
<br />
A character or token attribute can be referenced from content portion of any type of line and is substituted when the line is executed. The general format for referencing a character attribute is [*ID:attribute]. ID can be a token ID or a character ID (these start with a dash). Additionally if you have specified a sourceToken or targetToken, you can substitute "S" or "T" for the ID (for example [*S:npc_type] will retrieve the npc_type attribute from the source token.<br />
<br />
By default, all attribute references will be pulled from the '''''character''''' object that the ID represents (either directly or by being a Token ID that represents a character).<br />
<br />
Keep in mind, that if you want to access the "max" of a character attribute (for example, the max hit points), then you cannot trust the name that your roll20 character sheet shows you when you hover your mouse over the max hit points. For example, this reference will not work: [*S:hp_max]. Instead, you need to use this reference: [*S:hp^].<br />
<br />
If your ID refers to a token, token attributes can be accessed by preceding the attribute name with "t-", for example [*S:t-aura1_radius]. Supported token attributes are:<br />
<br />
{|<br />
| t-name || t-id || t-statusmarkers || t-bar1_value<br />
|-<br />
| t-bar1_max || t-bar2_value || t-bar2_max || t-bar3_value<br />
|-<br />
| t-bar3_max || t-top || t-left || t-width<br />
|-<br />
| t-height || t-rotation || t-layer || t-aura1_radius<br />
|-<br />
| t-aura1_color || t-aura2_radius || t-aura2_color || t-aura1_square<br />
|-<br />
| t-aura2_square || t-tint_color || t-light_radius || t-light_dimradius<br />
|-<br />
| t-light_angle || t-light_losangle || t-light_multiplier || t-light_otherplayers<br />
|-<br />
| t-light_hassight || t-flipv || t-fliph || t-controlledby<br />
|-<br />
| t-_cardid || t-_pageid || t-imgsrc || t-bar1_link<br />
|-<br />
| t-bar2_link || t-bar3_link || t-represents || t-layer<br />
|-<br />
| t-isdrawing || t-name || t-gmnotes || t-showname<br />
|-<br />
| t-showplayers_name || t-showplayers_bar1 || t-showplayers_bar2 || t-showplayers_bar3<br />
|-<br />
| t-showplayers_aura1 || t-showplayers_aura2 || t-playersedit_name || t-playersedit_bar1<br />
|-<br />
| t-playersedit_bar2 || t-playersedit_bar3 || t-playersedit_aura1 || t-playersedit_aura2<br />
|-<br />
| t-lastmove || t-adv_fow_view_distance || t-has_bright_light_vision || t-has_night_vision<br />
|-<br />
| t-night_vision_distance || t-emits_bright_light || t-bright_light_distance || t-emits_low_light<br />
|-<br />
| t-low_light_distance || t-has_limit_field_of_vision || t-limit_field_of_vision_center || t-limit_field_of_vision_total<br />
|-<br />
| t-has_limit_field_of_night_vision || t-limit_field_of_night_vision_center || t-limit_field_of_night_vision_total || t-has_directional_bright_light<br />
|-<br />
| t-directional_bright_light_center || t-directional_bright_light_total || t-has_directional_dim_light || t-directional_dim_light_center<br />
|-<br />
| t-directional_dim_light_total || t-lightColor || || |<br />
|}<br />
<br />
'''''It is important to note that some attributes names on tokens have corresponding attribute names on characters, which represent different values. For example, [*T:id] returns the character ID, while [*T:t-id] returns the token ID.'''''<br />
<br />
=== Subroutine Parameters ===<br />
<br />
When using a gosub statement (-->) or a conditional marked as a gosub (prefixing the label with a > character), you can pass any number of parameters separated by semicolons (;) that the code in the subroutine can utilize.<br />
<br />
Subroutine parameters are numbered starting at 1, and are accessed by using the notation [%number%], so the first parameter is [%1%], the second is [%2%], etc.<br />
<br />
Parameter substitution happens on all line types, and happens prior to character attribute references or roll variable substitution.<br />
<br />
=== Campaign Attribute ===<br />
You can retrieve properties of the API's Campaign object with the [*C:attributename] syntax. For example, [*C:playerpageid] will retrieve the current player ribbon page from the Campaign object.<br />
<br />
=== Page Attributes ===<br />
If you have set the '''activepage''' parameter, you can retrieve page-related properties with the [*P:attributename] syntax, including the page's UDL parameters.<br />
<br />
=== Repeating Section Values ===<br />
<br />
You can reference repeating attribute data using the syntax [*R:attributename] syntax (similar to referencing standard character attributes). The currently active repeating row information will be used to retrieve attribute values. You can also retrieve the full attribute name for a repeating row attribute by using the [*R>attributename] notation. This is useful to pass to things like chatsetattr.<br />
<br />
=== Array Elements ===<br />
After an array has been declared, the elements can be referenced with [@arrayName(index)]. Array indices start at 0.<br />
<br />
== Deferred Resolution for Meta Scripts ==<br />
<br />
As of 1.2.9, ScriptCards supports a deferral character for use when calling another API script with via the --@ statement, to defer processing of meta script references so they get processed prior to the sub-API call insted of prior to ScriptCards execution. To defer this processing for meta script (SelectManager, Fetch) by inserting a deferral character into the meta call. For example, if I want to have ScriptCards call TokenMod as if the token for "Quej Gr'stra" (yes, I let Roll20 name my test NPCs) I could use something like this:<br />
<br />
--@token-mod|{^& select Quej Gr'stra} _on showname<br />
<br />
The "^" in between { and & will prevent SelectManager from seeing the call when the ScriptCard script is processed, but the --@ statement will remove the deferral character so the command that will be sent by ScriptCards is:<br />
<br />
!token-mod {& select Quej Gr'stra} --on showname<br />
<br />
With the deferral character removed, SelectManager will see the {& select ...} and do its magic.<br />
<br />
While the default deferral character is "^", the deferral character is a setting that can be changed:<br />
<br />
--#deferralcharacter|%<br />
<br />
Will make % the deferral character for future --@ statements in the running script.<br />
<br />
There are currently three supported Meta script structures: {^&...} for SelectManager, @^(...) and *^(...) for fetch, where the ^ in the structures here represents the placement of the deferral character.<br />
<br />
== Arrays ==<br />
<br />
Arrays are a new data type introduced in version 1.1.12 of ScriptCards, and are manipulated with associated function (--~) commands.<br />
<br />
* Arrays are a lists of strings. Items in an array cannot contain the semi-colon (;) character, as that is used to separate parameters in the function code that deals with arrays.<br />
* Arrays are accessed via the --~ script command. In some cases, the value of the tag (variable name) for array commands is not used, and can be a dummy value or simply omitted. I have omitted them in the statements below.<br />
* All commands that DO return a value return string values, even if the content is numeric.<br />
* If a command returns a value and there is some sort of reason that it isn't an array value, you will get "ArrayError" in the return value. This can happen if you reach the end of an array while stepping through it, for example, so checking for "ArrayError" can serve as the end condition for a loop.<br />
* Each array keeps track of its current index, allowing you to step forward and backwards through arrays.<br />
* Any number of arrays can be defined.<br />
* Unlike string variables and roll variables, array variables cannot (currently) be referenced directly. It is necessary to use the function (--~) syntax to manipulate arrays and get values from them as strings for use in other parts of your script.<br />
<br />
<br />
== Reentrant Scripts ==<br />
<br />
Reentrant scripts allow you to create buttons in your script code that will re-execute the script at a given label within the code. If you set the reentrant setting (--#reentrant|somevalue) to a non-zero value, your setting and variable information will be preserved between executions. Reentrant script can be used to present menus or choices and then continue acting.<br />
<br />
Reentrant buttons are created with the [rbutton]Caption::ReentryLabel;Parameter[/rbutton] construct. The caption will be displayed on the generated button. ReentryLabel is the name of a label in your script that the button will jump to when clicked, and Parameter will be passed in as a string value called "reentryval".<br />
<br />
Example:<br />
<pre><br />
!script {{<br />
--#reentrant|testing<br />
--=Roll|1d20<br />
--+Roll|[$Roll]<br />
--&String|That was a [$Roll.Raw]!<br />
--~x|array;define;MyArray;Apple;Banana;Orange<br />
--+Try it|[rbutton]Hello!::EXEC_PC_SPELL;9[/rbutton]<br />
--X|<br />
<br />
--:EXEC_PC_SPELL|<br />
--+ReentryVal|[&reentryval]<br />
--+The value of Roll is|[$Roll]<br />
--+Value of String|[&String]<br />
--+Array|[@MyArray(0)]<br />
--X|<br />
}}<br />
</pre><br />
<br />
This script sets up some variables and then displays a button labeled "Hello!". If the user clicks the button, the script will be re-entered starting at the "EXEC_PC_SPELL", which will display the content of the variables from the original execution.<br />
<br />
'''''Note: This section needs to be expanded upon'''''<br />
<br />
== Procedure Libraries ==<br />
<br />
You can now create handouts in your game in Roll 20 with the name format "ScriptCards Library NAME", where name is a name you assign to the library. Library names are case sensitive. It is my hope that the more proficient ScriptCards scripters out there will provide procedure libraries (or procedures that can be included in libraries) for others to use to make their scripting life easier. Be they specific to a game system, or to a type of activity, I think a robust set of libraries that GMs could use to enhance their scripting capabilities would be very valuable to the community. Should such things begin to emerge, I’ll create a portion of the ScriptCards Wiki page to house them.<br />
<br />
To include one or more libraries in a script, use the +++libname+++ directive (does not need a -- line associated with it). Multiple library names can be specified by separating them with semicolons (i.e., +++General;dnd5elib;Colorize+++ would include three libraries (General, dnd5elib, and Colorize).<br />
<br />
Included libraries are separated from the main script code by the automatic inclusion of "--X|" before the first library is appended to the script, and all libraries are loaded at the end of the script before script processing takes place.<br />
<br />
Procedures and labels in libraries can be used just as if they were included in the body of your script. Note that this DOES mean that you could, technically, jump into a library with a direct branch (--^) or direct branch conditional, but I recommend using libraries to store reusable procedures.<br />
The Notes section of the library handout stores the library code, and is written just like any other ScriptCards code except:<br />
<br />
* They cannot use roll queries (?{Some Prompt:}) to get information from the user at execution time.<br />
* They cannot use @{} notation to access character and token information.<br />
<br />
Both of these limitation stem from the fact that Procedure Libraries are not processed by the chat server, which is what handles these items.<br />
<br />
Here is an example of handling damage modifications (resistance, vulnerability, and immunity) in D&D 5E with a library:<br />
<br />
<pre><br />
!script {{<br />
+++dnd5elib+++<br />
--#|Damage Modifiers Test<br />
--#targettoken|@{target|token_id}<br />
-->Lib5E_CheckDamageModifiers|ResistType;fire<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] fire damage<br />
<br />
-->Lib5E_CheckDamageModifiers|ResistType;cold<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] cold damage<br />
<br />
-->Lib5E_CheckDamageModifiers|ResistType;poison<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] poison damage<br />
<br />
-->Lib5E_CheckDamageModifiers|ResistType;acid<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] acid damage<br />
<br />
--X|<br />
}}<br />
</pre><br />
<br />
Library content (In a handout called “ScriptCards Library dnd5elib” NOTE: Paste into Notepad first and then paste into the handout in Roll20 to avoid bringing over HTML formatting from the web site):<br />
<br />
<pre><br />
--/|ScriptCards Library: dnd5elib version 0.0.1<br />
--/|Provides various utility procedures for D&D 5E games<br />
<br />
--/|Lib5E_CheckDamageModifiers handle damage resistance, vulnerability, and immunity. <br />
--/|Pass a string variable to be filled with a string to be appended to a dice roll and the damage type <br />
<br />
--:Lib5E_CheckDamageModifiers|damageVariableName;damageType<br />
--&[%1%]|<br />
--?"[*T:npc_vulnerabilities]" -inc "[%2%]"|>_Lib5E_IsVulnerable;[%1%]<br />
--?"[*T:npc_resistances]" -inc "[%2%]"|>_Lib5E_IsResistant;[%1%]<br />
--?"[*T:npc_immunities]" -inc "[%2%]"|>_Lib5E_IsImmune;[%1%]<br />
--<|<br />
<br />
--:_Lib5E_IsVulnerable| --&[%1%]| * 2 [Vulnerable] --<|<br />
--:_Lib5E_IsResistant| --&[%1%]| \ 2 [Resistant] --<|<br />
--:_Lib5E_IsImmune| --&[%1%]| * 0 [Immune] --<|<br />
</pre><br />
<br />
The idea is that the functions in the library create a string that can be appended to a roll to modify the output based on resistances, so you pass Lib5E_CheckDamageModifiers the name of the string variable you want to use and the damage type. The variable (ResistType in this case) will include either nothing, “* 2 [Vulnerable]”, “\ 2 [Resistant]”, or “* 0 [Immune]” which can be included in a roll assignment (--=) to modify the damage as appropriate. The order here might be important if an NPC is misconfigured to be both resistant and immune to the same damage type. Since immune is an absolute, having it last ensures that it will override resistant or vulnerable. A creature that is both vulnerable and resistant (again, misconfigured) will come back as resistant since that condition is checked after vulnerable.<br />
Some notes: I prefix my library labels with either “Lib5E_” or “_Lib5E_” as a clarity convention. This isn’t strictly necessary but you should be aware that if two libraries (or if your script and a library) define the same label, the last label defined will win. Since libraries are appended to the end of the script in the order you include them in the +++libname+++ directive, you can somewhat control this, but it is probably best to avoid re-declaring labels. <br />
<br />
In my case, items beginning with “Lib5E_” are intended to be called by scripts, while items beginning with “_Lib5E_” are intended to be used as subroutines by the “public” procedures. Of course, there is no reason you couldn’t call them directly.<br />
<br />
You might also note that I’ve included some library information in comment lines (--/|) at the top of the library. These are ignored by ScriptCards, and are a good way to convey requirements, parameters, usage information, etc.<br />
<br />
== Example Libraries ==<br />
<br />
=== dnd5elib ===<br />
<br />
[https://github.com/kjaegers/ScriptCards Download the dnd5elib Library from the ScriptCards GitHub]<br />
<br />
The '''dnd5elib''' library provides a collection of utility procedures that help simplify dealing with the D&D 5E Official Sheet. Some of the procedures in this library require '''chatsetattr''' to be installed in your game. This is a growing library, and currently only has a handful of routines. They are:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Procedure Name !! Notes<br />
|-<br />
| style="white-space:nowrap" | Lib5E_CheckDamageModifiers || This procedure can be used to evaluate vulnerabilities, resistances, and invulnerabilities on an NPC. After setting the --#target| parameters, pass the Lib5E_CheckDamageModifiers procedure a variable name (no reference information) and a damage type (i.e., fire, cold, bludgeoning, etc.) and a string variable with the name passed in as the first parameter will be created that contains text that can be included in a roll line (--=) in order to modify the roll as appropriate. For example, '''-->Lib5E_CheckDamageModifiers|ResistType;fire''' will check the current target character's attributes for "fire" and will either return an empty string (no references), "* 0 [Immune]" if the creature is immune, "\ 2 [Resistant]" if the creature is resistant, or "* 2 [Vulnerable]" if the creature is vulnerable to fire damage.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_DeductSpellSlot || Pass in a character_id and a slot level, and the script will expend one spell slot of that level, capping the value at 0 slots remaining. For Example '''<nowiki>-->Lib5E_DeductSpellSlot|@{selected|character_id};1</nowiki>''' to deduct a first level spell slot from the selected character.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_FindResource || Used to locate a resource value on a character. Pass in a character_id, a resource name, and two variable names. The procedure will check both repeating and non-repeating resources looking for a resource whose name matches what was passed in and return three variables. The first will be a string variable named for the 3rd parameter and contains the attribute name of the resource's "name" field. The second will be a string variable named after parameter 4 and contains the resource's value field attribute name, and the third variable is a Roll Variable, also named after the 4th parameter that contains the current resource value. Example: '''<nowiki>-->Lib5E_FindResource|@{selected|character_id};Crossbow bolts;ResName;ResValue</nowiki>''' will find "Crossbow bolts" as a resource on the character and return [&ResName] which is the name of the resource attribute, [&ResValue] which is the '''name of the attribute that stores the value''' and [$ResValue] which is the current numeric value of the resource.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Global_Attack_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Attack Modifiers (repeating_tohitmod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Bless" for 1d4 active and "Being Cool" for +2 active, I will get a return string " + 1d4 [Bless] + 2 [Being Cool]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Save_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Save Modifiers (repeating_savemod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Bless" for 1d4 active and "Being Cool" for +2 active, I will get a return string " + 1d4 [Bless] + 2 [Being Cool]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Skill_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Skill Modifiers (repeating_skillmod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Guidance" for 1d4 active and "Being Cool" for +2 active, I will get a return string " + 1d4 [Guidance] + 2 [Being Cool]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_AC_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Save Modifiers (repeating_savemod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Shield of Faith" with a value of 2 active, I will get a return string " + 2 [Shield of Faith]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Damage_Modifiers || Pass a character ID and TWO string variable to set the return value. The first string will be for normal damage, and the second will be the additional damage on a crit. This procedure will look through the Global Damage Modifiers (repeating_damagemod_*) for rows that are active (checked on the character sheet) and return two strings with the dice rolls and descriptions for them (for example, if I have "Sneak Attack" with a value of 1d6 normal and 1d6 critical damage active, I will get a return string " + 1d6 [Sneak Attack]" and another string of " + 1d6 [Sneak Attack CRIT]" that can be used in a dice rolls.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_DivineSmiteDice || Used to calculate the number of dice to be rolled for a paladin's Divine Smite. Pass a target token id, a spell slot level, and a string variable to be set to the dice roll amount based on the NPC_TYPE attribute of the target token. The returned variable will contain a dice roll (like "3d8" that can be used in a --= line)<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Character_Summary || Outputs a mini character sheet, including clickable buttons for attacks, actions, legendary actions, etc. Will automatically detect a PC vs NPC and output the appropriate sections.<br />
|}<br />
<br />
Due to formatting issues with the Wiki, the library code has been moved to a [https://gist.github.com/kjaegers/52f6049ddd257f0a1288aca4bbde13c5 GITHUB GIT]. Please view the GIST in raw mode and copy the text and paste it into a handout called "ScriptCards Library dnd5elib" in your Roll20 Game.<br />
<br />
== What to Know if you are Coming from PowerCards ==<br />
<br />
''Note: This section is a work in progress.''<br />
<br />
While ScriptCards and PowerCard have very similar output goals, their internals and use are quite different. The table below summarizes some of the major differences between the scripts.<br />
<br />
::{| class="wikitable"<br />
|-<br />
! PowerCards !! ScriptCards <br />
|-<br />
| With a handful of exceptions, all lines in a PowerCard macro are intended to produce a line of output on the final card. || With ScriptCards, ONLY the <code>--+</code> and <code>--*</code> statement types produces output <br />
|-<br />
| PowerCards lines begin with two dashes (<code>--</code>) followed by a unique tag name for the line, followed by a vertical bar and the content for the line. || ScriptCards lines begin with two dashes (<code>--</code>) followed by a '''statement type identifier''', which is a single character that identifies the type of line to the interpreter. This is followed by a tag (frequently optional), a vertical bar, and the parameters for the statement being executed.<br />
|-<br />
| PowerCard macros are always processed top to bottom. Lines can be hidden so they don't output anything, but there is no looping or branching (--SkipTo looks like a branch, but it just hides all of the lines until the referenced label. || ScriptCards scripts support true branching, including direct branching (<code>--^</code>) and procedure branching (<code>--></code>) and (<code>--<</code>). Procedures support parameters and a call stack so procedures can be nested to call other procedures.<br />
|-<br />
| All lines in a PowerCards macro need to have unique tags because PowerCards builds the card as a single JavaScript object using the tag names to store what will be displayed. This is why repeated tag names always result in the last one being shown. || ScriptCards tags do not need to be unique, and in the case of many line types are optional.<br />
|-<br />
| PowerCards conditionals result in either showing or hiding the line they are on. || ScriptCards conditionals '''''only''''' support branching as the result of the comparison. This branching can be direct (a GOTO) or procedural (a GOSUB) '''''NOTE: As of version 1.2.0, ScriptCards also supports roll/string variable assignment as a result of conditional evaluation'''''<br />
|-<br />
| PowerCards relies on the Roll20 [[Quantum Roll]] server and inline rolls for all dice functions || ScriptCards includes its own dice roll parser, and '''''does not support''''' inline rolls.<br />
|-<br />
| PowerCards RollIDs (often mistaken for variables) are assigned by analyzing the results of an inline roll, and cannot be referenced in other rolls, so you can't roll a <code>1d4</code> and then roll a <code>1d20</code> and add the <code>1d4</code> result because all of the rolls happen on the chat server before PowerCards gets the macro text. || ScriptCards supports two types of variables: Roll Variables and String Variables. Because ScriptCards uses its own roll parser and is not dependent upon the chat server, rolls and their results can be used in other rolls, math functions, output, etc.<br />
|}<br />
<br />
== Example Scripts ==<br />
<br />
Below are some sample scripts that utilize the various statement types in ScriptCards:<br />
<br />
=== Divine Smite ===<br />
<br />
This script will prompt the user for a spell slot level to expend on a divine smite. It will check the target's npc_type to see if it is an Undead or Fiend, which adds an additional d8 to the smite roll.<br />
<br />
[[File:ScriptCards Divine Smite.png|Divine Smite Script Output]]<br />
<br />
<pre><br />
!scriptcard {{<br />
--#title|Divine Smite<br />
--=DiceCount|?{Spell Slot Level?|1|2|3|4|5|6|7|8|9} + 1<br />
--=IsFiendOrUndead|0<br />
--?"@{target|npc_type}" -inc fiend|>IsBoosted<br />
--?"@{target|npc_type}" -inc undead|>IsBoosted<br />
--=TotalDice|[$DiceCount] + [$IsFiendOrUndead]<br />
--=SmiteRoll|[$TotalDice]d8<br />
--#emoteText|@{selected|token_name} smites @{target|token_name}<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
--+Smite|deals [$SmiteRoll] radiant damage.<br />
--X|<br />
<br />
--:IsBoosted|<br />
--=IsFiendOrUndead|1<br />
--<|<br />
}}<br />
</pre><br />
<br />
==== How It Works ====<br />
<br />
The first line sets the "title" card parameter to "Divine Smite".<br />
<br />
Line 2 Shows a query to the user asking for the spell slot level, adds one and stores the value in the "DiceCount" Roll Variable. The query/dropdown is generated by the chat server prior to the script being executed.<br />
<br />
Line 3 defaults the "IsFiendOrUndead" Roll Variable to 0.<br />
<br />
Lines 4 and 5 compare the target's "npc_type" attribute (passed by the chat server as text) to see if they include either "undead" or "fiend". If true, the IsBoosted subroutine will be called. No parameters are passed to this subroutine.<br />
<br />
Line 6 sets the "TotalDice" variable to the base (DiceCount) number plus the IsFiendOrUndead number, which will be a 0 or a 1.<br />
<br />
Line 7 calculates "SmiteRoll" by rolling a number of d8 equal to the "TotalDice" value.<br />
<br />
Lines 8-10 set the parameters for the emote, which appears above the card content. By setting the sourceToken and the targetToken, their icons will appear in the emote surrounding the text describing the action.<br />
<br />
Line 11 is the only line that actually produces output on the card. It results in "Smite deals # radiant damage".<br />
<br />
Line 12 ends the script execution, preventing the script from continuing and running the subroutines out of context.<br />
<br />
Lines 14-16 are the IsBoosted subroutine, starting with the :IsBoosted label. The IsFiendOrUndead variable is set to 1, and a return from subroutine is executed.<br />
<br />
=== Magic Missile ===<br />
<br />
This script demonstrates using a loop and calling a subroutine to fire a number of missiles determine by the spell slot level used to cast the spell.<br />
<br />
[[File:ScriptCards_MagicMissile_Fixed.png|Magic Missile Script Output]]<br />
<br />
<pre><br />
!scriptcard {{ <br />
--#title|Magic Missile<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
--=MissileCount|?{Spell Slot Level?|1|2|3|4|5|6|7|8|9} + 2<br />
--=DisplayCount|1<br />
--=MissileDamage|0<br />
--#leftsub|Slot level ?{Spell Slot Level?}<br />
--#rightsub|Ranged Attack<br />
--#emoteText|Fred uses a level ?{Spell Slot Level?} spell slot to fire [$MissileCount.Total] missiles of magical force!<br />
--:MissileLoop|<br />
-->FireMissile|<br />
--=DisplayCount|[$DisplayCount] + 1<br />
--?[$DisplayCount] -le [$MissileCount]|MissileLoop<br />
--+Total|Total damage is [$MissileDamage]<br />
--X|<br />
<br />
--:FireMissile|<br />
--=ThisMissile|1d4 + 1<br />
--=MissileDamage|[$MissileDamage] + [$ThisMissile]<br />
--+Missile|[$DisplayCount.Total] Hits for [$ThisMissile] [b]force[/b] damage<br />
--<|<br />
}}<br />
</pre><br />
<br />
==== How It Works ====<br />
<br />
Lines 1-3 set the card title, the source token and the target token. Setting these tokens causes their icons/avatars to appear in the Emote section of the card.<br />
<br />
Line 4 asks the user what spell slot level they wish to use to cast magic missile. The number of missiles fired is equal to 2 plus the spell level, and this is stored in the MissileCount variable.<br />
<br />
Line 5 stores a 1 in the DisplayCount variable. This will be used to control the loop to determine the number of missiles fired and the missile number when displaying damage rolls.<br />
<br />
Line 6 initializes MissileDamage to 0<br />
<br />
Line 7 sets the left subtitle to the text "Slot Level #", where # is the spell slot level being used.<br />
<br />
Line 8 sets the right subtitle to the text "Ranged Attack".<br />
<br />
Line 9 sets the emoteText parameter with a description of the action, including the slot level and number of missiles fired.<br />
<br />
Line 10 is a label for the missile firing loop<br />
<br />
Line 11 Calls the "FireMissile" subroutine<br />
<br />
Line 12 increases the DisplayCount variable by 1<br />
<br />
Line 13 Checks to see if there are still missles to fire (DisplayCount <= MissileCount) and if so branches to MissileLoop<br />
<br />
Line 14 Displays the total damage dealt by the spell.<br />
<br />
Line 15 stops execution of the script to prevent out of context execution of the subroutine.<br />
<br />
Lines 76-21 are the FireMissile subroutine, beginning with the FireMissile label. The 1d4+1 is rolled and assigned to "ThisMissile". The result is added to the existing MissileDamage total, and a line for the current missile is displayed with the missile number and the damage for the missile.<br />
<br />
=== Longsword Attack ===<br />
<br />
This script demonstrates a standard 5E D&D melee weapon attack, including detection of misses, fumbles, hits, and critical hits. If installed, alterbars is used to decrement the target's BAR3 value by the damage dealt.<br />
<br />
[[File:ScriptCards Longsword.png|Longsword Script Output]]<br />
<br />
<pre><br />
!scriptcard {{<br />
--#title|Longsword<br />
--#leftsub|Melee Attack<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
--#emoteText|@{selected|token_name} attacks @{target|token_name}<br />
--=TargetAC|@{target|npc_ac}<br />
--?[$TargetAC.Total] -gt 0|DoneWithAC<br />
--=TargetAC|@{target|ac}<br />
--:DoneWithAC|<br />
--=AttackRoll|1d20 + @{selected|strength_mod} [STR] + @{selected|pb} [PROF]<br />
--+Attack|@{selected|token_name} rolls [$AttackRoll] vs AC [$TargetAC].<br />
--?[$AttackRoll.Base] -eq 20|Crit<br />
--?[$AttackRoll.Base] -eq 1|Fumble<br />
--?[$AttackRoll.Total] -ge [$TargetAC.Total]|Hit<br />
--+Miss|The attack missed.<br />
--^Final|<br />
<br />
--:Fumble|<br />
--+Fumble!|The attack went horribly wrong.<br />
--^Final|<br />
<br />
--:Hit|<br />
--=Damage|1d8 + @{selected|strength_mod} [STR]<br />
--+Hit!|The attack hit @{target|token_name} for [$Damage] slashing damage.<br />
--@alter|_target|@{target|token_id} _bar|3 _amount|-[$Damage]<br />
--^Final|<br />
<br />
--:Crit|<br />
--=Damage|1d8 + @{selected|strength_mod} [STR] + 1d8 [CRIT]<br />
--+Critical Hit!|The attack hit @{target|token_name} for [$Damage] slashing damage.<br />
--@alter|_target|@{target|token_id} _bar|3 _amount|-[$Damage]<br />
<br />
--:Final|<br />
}}<br />
</pre><br />
<br />
==== How it Works ====<br />
<br />
In lines 1-5, we set the title, subtitle, and emote text along with the tokens for the emote area.<br />
<br />
Lines 6-9 allow us to determine the AC of the target. On the 5E Roll20 sheet, NPCs armor class is stored in "npc_ac", while PCs armor class is in "ac". First we grab npc_ac and if it is zero, we check AC.<br />
<br />
Line 10 rolls the attack roll, rolling 1d20 and adding the attacker's strength modifier and proficiency bonus<br />
<br />
Line 11 displays the result of the attack roll on the card<br />
<br />
Lines 12-14 determine what kind of result the attack had. If the .Base value of the roll was 20, we branch to "Crit". If it was 1, we branch to "Fumble". If the .Total value of the roll was greater than or equal to the AC that was determined in Lines 6-9, we branch to Hit.<br />
<br />
Assuming we didn't branc anywhere, the result of the attack was a miss, so we display that on line 15 and then branch to "Final"<br />
<br />
This is followed by three branch segments, :Fumble, :Hit, and :Crit. A fumble displays a text message and branches to :Final.<br />
<br />
On a hit or a crit, we roll Damage (adding additional damage dice on a crit). We display a "Hit!" or "Critical Hit!" message and then make an API call to AlterBars, passing it the token id, bar we want to modify (3 in this case), and the amount we want to modify by the Damage value.<br />
<br />
=== Party Health Status ===<br />
<br />
This example calculates the current Hit Points remaining and HP percentage for each character and creates a color-coded display with the current party status.<br />
<br />
[[File:ScriptCards Party Health.png]]<br />
<br />
<pre><br />
!scriptcard {{<br />
--#title|Party Status<br />
--#titleCardBackground|#33CC33<br />
--#oddrowbackground|#bfee90<br />
--#evenrowbackground|#90eebf<br />
-->HealthCheck|@{Quej Grastra|character_id}<br />
-->HealthCheck|@{Brim Cheuto|character_id}<br />
-->HealthCheck|@{Odug Ututees|character_id}<br />
--X|End of card Execution<br />
<br />
--:HealthCheck|<br />
--=HealthPerc|[*[%1%]:hp] / [*[%1%]:hp^] * 100 \ 1<br />
--=HealthColor|000000<br />
--?[$HealthPerc.Total] -gt 50|HealthSkip<br />
--=HealthColor|FF0000<br />
--:HealthSkip|<br />
--+[*[%1%]:character_name]|has [#[$HealthColor.RollText]][*[%1%]:hp] of [*[%1%]:hp^][/#] HP [R]([$HealthPerc.Total]%)[/R]<br />
--<|End of HealthCheck<br />
}}<br />
</pre><br />
<br />
==== How it Works ====<br />
<br />
Lines 1-4, we set the card title, and set the title background and row background colors to shades of green.<br />
<br />
Lines 5-7 make gosub calls the the "HealthCheck" subroutine, passing in the character ID of each of the named characters (these are the names of the characters in my test game)<br />
<br />
Line 8 terminates the script execution.<br />
<br />
The remaining lines of the script are the HealthCheck subroutine, which works like this:<br />
<br />
Line 10 is the subroutine label (:HealthCheck)<br />
<br />
Line 11 uses the character id passed as a parameter and combines it with character attribute lookup *(...) to retrieve the value of "hp" and "hp<nowiki>^</nowiki>" for the character. The <nowiki>^</nowiki> character is used to specify that we want the MAX value for this attribute for the second call. We divide these two numbers and multiple by 100 to get a percentage. Finally, we use integer division by 1 to round the percentage and drop the decimals. The end result gets stored in the HealthPerc roll variable.<br />
<br />
Line 12 defaults to color of the health text to black<br />
<br />
Line 13 check to see if the health percentage is greater than 50. If so, it branches to HealthSkip, preventing the script from executing line 13.<br />
<br />
Line 14 sets the color of the health text to red<br />
<br />
Line 15 is the label that will be branched to from Line 13 to skip the red coloring<br />
<br />
Line 16 again uses character attribute substitution and the passed parameter value to output a display line containing the character name, the colorized health total, and the percentage value. The percentage is right-justified.<br />
<br />
Line 17 returns from the HealthCheck subroutine.<br />
<br />
=== Expanded Magic Missile Script ===<br />
<br />
This is the expanded and enhanced version of the Magic Missile script covered in {{yt|watch?v=u50xvNzS9Zk | this video}}. It includes visual and audio effects, checking and deducting spell slots, and applying damage using either Token-Mod or Alterbars.<br />
<br />
<pre><br />
!scriptcard {{ <br />
--#title|Magic Missile<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
<br />
-->GetAndCheckSlotInformation|<br />
<br />
--=MissileCount|[$SlotLevel] + 2<br />
--=DisplayCount|1<br />
--=MissileDamage|0<br />
--#leftsub|Slot level [$SlotLevel]<br />
--#rightsub|Ranged Attack<br />
--#emoteText|@{selected|character_name} uses a level [$SlotLevel.Total] spell slot to fire [$MissileCount.Total] missiles of magical force!<br />
<br />
--:MissileLoop|<br />
-->FireMissile|<br />
--=DisplayCount|[$DisplayCount] + 1<br />
--?[$DisplayCount] -le [$MissileCount]|MissileLoop<br />
--+Total|Total damage is [$MissileDamage]<br />
-->DeductSpellSlot|<br />
--#rightsub|Level [$SlotLevel] Left: [$SlotsRemaining] <br />
-->PlayEffects|none;burst-smoke;beam-magic;spell_01<br />
-->ApplyDamageTokenmod|@{target|token_id};3;-[$MissileDamage]<br />
-->ApplyDamageAlterbars|@{target|token_id};3;-[$MissileDamage]<br />
--X|<br />
<br />
--:FireMissile|<br />
--=ThisMissile|1d4 + 1<br />
--=MissileDamage|[$MissileDamage] + [$ThisMissile]<br />
--+Missile|[$DisplayCount.Total] Hits for [$ThisMissile] [b]force[/b] damage<br />
--<|<br />
<br />
--:GetAndCheckSlotInformation|<br />
--=SlotLevel|?{Spell Slot Level?|1|2|3|4|5|6|7|8|9}<br />
--=SlotsTotal|[*S:lvl[$SlotLevel]_slots_total]<br />
--=SlotsExpended|[*S:lvl[$SlotLevel]_slots_expended]<br />
--?[$SlotsExpended.Total] -ge [$SlotsTotal.Total]|NoSlotsLeft<br />
--<|<br />
<br />
--:NoSlotsLeft|<br />
--+|[*S:character_name] has no level [$SlotLevel.Total] spell slots available.<br />
--X|<br />
<br />
--:DeductSpellSlot|<br />
--=SlotsExpended|[$SlotsExpended] + 1<br />
--@setattr|_charid [*S:character_id] _lvl[$SlotLevel]_slots_expended|[$SlotsExpended] _silent<br />
--=SlotsRemaining|[$SlotsTotal] - [$SlotsExpended]<br />
--<|<br />
<br />
--:PlayEffects|Parameters are : source effect; target effect; line effect; sound effect<br />
--vtoken|@{selected|token_id} [%1%]<br />
--vtoken|@{target|token_id} [%2%]<br />
--vbetweentokens|@{selected|token_id} @{target|token_id} [%3%]<br />
--@roll20AM|_audio,play,nomenu|[%4%]<br />
--<|<br />
<br />
--:ApplyDamageTokenmod|Parameters are tokenid;bar#;amount<br />
--@token-mod|_ignore-selected _ids [%1%] _set bar[%2%]_value|[%3%]<br />
--<|<br />
<br />
--:ApplyDamageAlterbars|<br />
--@alter|_target|[%1%] _bar|[%2%] _amount|[%3%]<br />
--<|<br />
}}<br />
</pre><br />
<br />
[[Category:Featured articles]]</div>5004103https://wiki.roll20.net/Script:ScriptCardsScript:ScriptCards2021-09-28T17:00:34Z<p>5004103: /* Comment (--/) */</p>
<hr />
<div>{{revdate}}<br />
== Introduction ==<br />
'''ScriptCards''' provides a script interpreter that can be used to create powerful macros that display the results of player/NPC actions, or display other information in a pleasing visual format in your game's chat window. The scripting language contains variables (both dice-roll (enhanced numerics) and strings) as well, conditionals, branching, subroutines with parameters, and a set of built-in functions to simplify working with Roll20 information.<br />
{{script overview<br />
|name=ScriptCards<br />
|author={{user profile|2365448|Kurt J.}}<br />
|code=<br />
|version=1.4.0e<br />
|lastmodified=2021-09-24}}<br />
ScriptCards is not game-system specific, and can be used with any system/sheet. Near the end of this Wiki there is a section set aside for libraries that can implement system-specific tasks, with the hope that enthusiasts playing particular systems will create and share utility functions that can be utilized by the wider community.<br />
<br />
The default display style for ScriptCards output is similar to the format used to document player and NPC abilities in Dungeons and Dragons 4th Edition, but does not have any system ties to D&D4E.<br />
<br />
Current OneClick Version : 1.4.0e<br />
<br />
Current Development Version : 1.4.4<br />
<br />
'''''<big>Critically Important: ScriptCards does not use/parse inline rolls. ScriptCards includes its own built-in dice roll parser to allow for the use of variables inside dice rolls. As of version 1.2.3, ScriptCards will now take inline rolls and substitute the total result value in statement strings, meaning that you can utilize inline rolls but ScriptCards will only see the result of the roll, and not parse the roll components itself.</big>'''''<br />
<br />
* {{fpl|9752053/ ScriptCards thread}}<br />
** {{fpl|10000297/ Scritpcard API Working and Sharing}}<br />
* https://github.com/kjaegers/ScriptCards/tree/main/ScriptCards_API - GitHub repository for source before the one-click version is updated.<br />
* {{yt.be|hyR7Jnq4mQM ScriptCards Intro}} 45min, Jan 2021<br />
* {{yt.be|u50xvNzS9Zk ScriptCards Magic Missile Deep Dive}} 39min, Feb 2021<br />
<br />
<br />
__TOC__<br />
=== Is ScriptCards Related to [[PowerCards]]? ===<br />
<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
Check the '''[[#What to Know if you are Coming from PowerCards|What to Know if you are Coming from PowerCards]]'''-section for a comparison table between the two scripts.<br />
<br />
== What is a ScriptCard Script ==<br />
<br />
A ScriptCard Script is text written into the chat window (either typed directly, pasted, or run via a macro) that will produce a card of information in the [[text Chat|chat window]]. A ScriptCard Script is composed of an [[API]] command: <code><nowiki>!scriptcard {{ }}</nowiki></code> enclosing any number of lines that determine the output that will be added to the card. At it simplest, the following macro:<br />
<br />
<pre>!scriptcard {{ }}</pre><br />
<br />
Will produce just a title card that displays “ScriptCards” as the name:<br />
<br />
[[File:Scriptcard blank.png]]<br />
<br />
Of course, this is just the simplest type of macro and isn’t very useful. In order to produce useful output, we need to include lines between the <code><nowiki>{{</nowiki></code> and <code><nowiki>}}</nowiki></code> that direct the API script as to what it should do.<br />
<br />
== Structure of a ScriptCard Line ==<br />
<br />
All ScriptCard lines begin with two dashes, followed by an ''statement identifier character'' that lets ScriptCards what type of line it is. There are several of these, and they are detailed in the next section. After the line type identifier, a Tag name 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.<br />
<br />
Following the Tag is a vertical bar, and then the content of the line itself. Again, each type of line might interpret this content differently.<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Identifier !! Statement Type !! Tag !! Content !! Notes<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--/</nowiki> || Comment || unused || unused || The <code>--/</code> 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--#</nowiki> || 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").<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--+</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--=</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--&</nowiki> || Assign String 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. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--@</nowiki> || 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 (i.e., [[TokenMod|!token-mod]], or [[ChatSetAttr|!setattr]], etc.)<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--:</nowiki> || 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<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--^</nowiki> || Branch To || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--></nowiki> || Call Procedure || 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<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--<</nowiki> || 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.<br />
|- <br />
| style="white-space:nowrap" | <nowiki>--?</nowiki> || Conditional Branch || Condition to be evaluated || True Branch Label<nowiki>|</nowiki>False Branch Label || The condition will be evaluated and execution will jump to one of the two indicated branches (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 included a semicolon separated list of parameters. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--s</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--l</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--v</nowiki> || 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+'''''<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--e</nowiki> || Echo to Chat || Name to send chat command as || Chat message to send || Variable substitution takes place on the tag and content.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--R</nowiki> || Retrieve Repeating Section Row information || "find", "first", or "next" || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--~</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--c</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--i</nowiki> || Information Request || User Prompt;Button Caption || InfoType;VariableName;ParameterText || See full documentation below.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--d</nowiki> || 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. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--%</nowiki> || 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. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--*</nowiki> || 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.<br />
|}<br />
<br />
== ScriptCard Statement Type Details ==<br />
The sections below detail the individual statement types supported by ScriptCards<br />
<br />
=== Comment (--/) ===<br />
<br />
A --/ statement is ignored by the ScriptCards parser. You can use this type of statement to add comments and informational text to your script. <br />
<br />
Example:<br />
<pre><br />
!script {{<br />
--/|Script Name : Fireball<br />
--/|Purpose : Allow the player to cast a fireball and blow stuff up!<br />
.<br />
.<br />
.<br />
}}<br />
</pre><br />
<br />
Using this style will sometimes work, but is not recommended, because it can lead to unwanted text appearing on your output card.<br />
<pre><br />
!script {{<br />
--/|When you have a very<br />
long comment, then<br />
you sometimes have<br />
to put it in multiple<br />
lines.<br />
.<br />
.<br />
.<br />
}}<br />
</pre><br />
<br />
=== Set Parameter (--#) ===<br />
<br />
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.<br />
<br />
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.<br />
<br />
'''''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.'''''<br />
<br />
Examples:<br />
<pre><br />
--#title|Magic Missile<br />
--#leftsub|Level 1 Spell<br />
--#rightsub|Force Damage<br />
</pre><br />
<br />
The three examples above set the “title”, “leftsub”, and “rightsub” values for the card to the content value for the line. <br />
<br />
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.<br />
Settings Lines do not produce output lines on the card.<br />
<br />
The following settings are available (note that parameter names are ''not'' case sensitive):<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Name !! Effect/Use !! Default Value !! Type<br />
|-<br />
| 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<br />
|-<br />
| allowplaintextinrolls || If set to a non-zero value, plain character text in rolls will be copied to the roll text || 0 || Per-Line<br />
|-<br />
| bodyFontFace || Name of the font used in the card rows || Helvetica || Global<br />
|-<br />
| bodyFontSize || Size of the text in the card rows || 14px || Global<br />
|-<br />
| bodybackgroundimage || Specify an image (content for a CSS background-image tag) for the body area || none || Global<br />
|-<br />
| buttonBackground || Background color for buttons created with [button][/button] || #1C6EA4 || Per-Line<br />
|-<br />
| buttonBorderColor || Border (outline) color for buttons created with [button][/button] || #999999 || Per-Line<br />
|-<br />
| buttonFontFace || Font Family specifier for captions on buttons created with [button][/button] || Tahoma || Per-Line<br />
|-<br />
| buttonFontSize|| Text size for captions on buttons created with [button][/button] || x-small || Per-Line<br />
|-<br />
| buttonTextColor|| Text color of labels on buttons created with [button][/button] || #FFFFFF || Per-Line<br />
|-<br />
| 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<br />
|-<br />
| deferralcharacter || Changes the meta script deferral sequence to the specified value || ^ || Per-Line<br />
|-<br />
| diceFontColor|| Color of the dice created with the [d4] [d6], etc. formatting markers || #1C6EA4 || Per-Line<br />
|-<br />
| dicefontsize || Size of the dice created with the [d4] [d6], etc. formatting markers || 3.0em || Per-Line<br />
|-<br />
| 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<br />
|-<br />
| disablerollprocessing || If set to a non-zero value, --= lines will not process dice rolls strings || 0 || Per-Line<br />
|-<br />
| emoteBackground || Background color of the emote area || #f5f5ba || Global<br />
|-<br />
| emoteFont || Name of the font used in emote area (above the title of the output card) || Georgia || Global<br />
|-<br />
| emoteFontColor || Color of the font in the emote area || None (Empty) || Global<br />
|-<br />
| emoteFontSize || Size of the font used in the emote area || 14px || Global<br />
|-<br />
| emoteFontWeight || Font weight for the font in the emote area || bold|| Global<br />
|-<br />
| emoteState || If set to anything other than "visible", the emote portion of the card will not be displayed || visible || Global<br />
|-<br />
| emoteText || Text to display in the emote portion of the card || None (Empty) || Global<br />
|-<br />
| emotefont || Name of the font used in the emote text area || font-family: Georgia, serif; font-weight: bold; || Global<br />
|-<br />
| evenRowBackground || Hex code for the background color for even rows || #eeeeee || Per-Line<br />
|-<br />
| evenRowFontColor || Hex code for the text color for even rows || #000000 || Per-Line<br />
|-<br />
| evenrowbackgroundimage || Specify an image (content for a CSS background-image tag) for the even card rows || none || Per-Line<br />
|-<br />
| executionlimit || Maximum number of script lines the interpreter will try to execute. This prevents "infinite loop" sandbox crashes || 40000 || Global<br />
|-<br />
| hideCard || If set to any non-default value, the entire card output will be suppressed || 0 || Global<br />
|-<br />
| 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<br />
|-<br />
| 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<br />
|-<br />
| lineheight || Vertical size of each line on the output card || normal || Per-Line<br />
|-<br />
| nominmaxhighlight || If set to anything other than "0", rolls will not display crit/fumble/mixed highlight colors. || 0 || Per-Line<br />
|-<br />
| norollhighlight || If set to anything other than "0", rolls will not be formatted (plain numbers) but will still get a tooltip with details ('''''v1.3.6b+''''') || 0 || Per-Line<br />
|-<br />
| oddRowBackground || Hex code for the background color for even rows || #d0e4f5 || Per-Line <br />
|-<br />
| oddRowFontColor || Hex code for the text color for odd rows || #000000 || Per-Line<br />
|-<br />
| oddrowbackgroundimage || Specify an image (content for a CSS background-image tag) for the odd crd rows || none || Per-Line<br />
|-<br />
| reentrant || Used to name a script for rentrant button use || 0 || Global<br />
|-<br />
| 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)0 || Global<br />
|-<br />
| rollhilightlineheight || Determines the height of the hilight box placed around roll results ('''''1.4.2+''''') || 1.0em || Per-Line<br />
|-<br />
| roundUp || If set to a non-default value, integer division will round up instead of down || 0 || Per-Line<br />
|-<br />
| showfromfornonwhispers || If set to a non-zero value, will include the sender on cards that aren't whispered || 0 || Global<br />
|-<br />
| 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<br />
|-<br />
| subtitleFontColor || Color of the text in the subtitle areas || #FFFFFF || Global<br />
|-<br />
| subtitleFontFace || Name of the font used on the subtitle sections || Tahoma || Global<br />
|-<br />
| subtitleFontSize || Size of the subtitle font || 13px || Global<br />
|-<br />
| subtitleSeperator || The character(s) that will be placed between leftsub and rightsub || <nowiki>&#x2666</nowiki>; || Global<br />
|-<br />
| tableBorderRadius || CSS specifier for how rounded the borders of the output card are. Use "0px;" for square borders || 6px; || Global<br />
|-<br />
| tableShadow || CSS specifier for the drop shadow under the output card || 5px 3px 3px 0px #aaa; || Global<br />
|-<br />
| tablebgcolor || Background color of the whole card. '''''Normally not visible''''' || #EEEEEE || Global<br />
|-<br />
| tableborder || Color of the border that surrounds the whole card || 2px solid #000000; || Global<br />
|-<br />
| 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<br />
|-<br />
| timezone || IANA Specifier for the local time zone, used in system/date functions || merica/New_York || Per-Line<br />
|-<br />
| title || Text displayed in the title area of the card || ScriptCards || Global<br />
|-<br />
| titleCardBackground || A hex color code representing the background color of the title area. || #1c6ea4 || Global<br />
|-<br />
| titleFontColor || Color of the text on the card title || #FFFFFF || Global<br />
|-<br />
| titleFontFace || Name of the font used on the title area || Contrail One || Global<br />
|-<br />
| titleFontLineHeight || Line spacing on the title area || 1.2em || Global<br />
|-<br />
| titleFontSize || Size of the title font || 1.2em || Global<br />
|-<br />
| titlecardbackgroundimage || Specify an image (content for a CSS background-image tag) for the title card area || none || Global<br />
|-<br />
| titlecardbottomborder || Border CSS specifier for the bottom of the title card area || 2px solid #444444; || Global<br />
|-<br />
| titlecardgradient || If set to non-zero value, will place a vertical gradient on the title card area || 0 || Global<br />
|-<br />
| usehollowdice || If set to a non-zero value, the hollow/outline versions of the dice fonts will be used || 0 || Per-Line<br />
|-<br />
| whisper|| Comma separated list of who to whisper the output to. Use "gm" for [[GM|GMs]] and "self" for the sender || none || Global|}<br />
|}<br />
<br />
''Setting Lines do not produce output lines on the card''<br />
<br />
=== Direct Output (--+) ===<br />
<br />
A direct output line display 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.<br />
<br />
Examples of Direct Output lines:<br />
<pre><br />
--+Hello|World<br />
--+Attack|The monster rolls [$Attack] to hit!<br />
--+Damage|@{target|token_name} is hit for [$Damage] [#3333AA][b]frost[/b][/#] damage.<br />
</pre><br />
<br />
Direct Output lines support inline formatting, roll variable replacement, character attribute references, and procedure variables.<br />
<br />
=== GM Output (--*) ===<br />
<br />
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. <br />
<br />
Example:<br />
<pre><br />
--+PlayerLine|This line is shown on the public card<br />
--*GMLine|This line will only be shown to GMs, on a separate card.<br />
</pre><br />
<br />
=== Roll Variable Assignment (--=) ===<br />
<br />
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.<br />
<br />
'''''All components of a roll equation should be separated with spaces.'''''<br />
<br />
Examples:<br />
<pre><br />
--=MissileDamage|1d4 + 1<br />
--=Attack|1d20 + @{selected|strength_mod} [STR] + @{selected|pb} [PROF]<br />
</pre><br />
<br />
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. Text enclosed in square brackets ([]) is considered "flavor text" and will be added to the result text but does not impact the roll result.<br />
<br />
The following dice formats are supported:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Format Pattern !! Example !! Description<br />
|-<br />
| XdY || 3d8 || Simple format. Roll a Y-sided die X times<br />
|-<br />
| XdYkhZ || 2d20kh1 || Roll Y-sided die X times and keep the highest Z number of dice<br />
|-<br />
| XdYklZ || 4d6kl3 || Roll Y-sided die X times and keep the lowest Z number of dice <br />
|-<br />
| XdY>Z || 5d6>3 || Roll Y-sided die X times and count a 1 for each roll greater than Z <br />
|-<br />
| XdY<Z || 5d6<3 || Roll Y-sided die X times and count a 1 for each roll less than Z <br />
|}<br />
<br />
'''''Note: The dice formulae below are supported in the development version of ScriptCards and will be merged with the table above when activated on OneClick'''''<br />
::{| class="wikitable"<br />
|-<br />
! Format Pattern !! Example !! Description<br />
|-<br />
| 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<br />
|-<br />
| 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<br />
|-<br />
| 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)<br />
|-<br />
| 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<br />
|}<br />
<br />
The following operators are supported in a roll equation:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Operator !! Operation<br />
|-<br />
| + || Addition <br />
|-<br />
| - || Subtraction <br />
|-<br />
| * || Multiplication <br />
|-<br />
| / || Division <br />
|-<br />
| \ || Integer Division (Rounds down) <br />
|-<br />
| % || Modulo (Remainder of Divison)<br />
|}<br />
<br />
Roll Variables can be accessed at any time after they have been created by using the [$VariableName] format, with the following optional modifiers:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Modifier !! Meaning<br />
|-<br />
| No modifier || In a Direct Output Line (<nowiki>--+</nowiki>) 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<br />
|-<br />
| .Total || The end result of the roll equation as an unformatted number <br />
|-<br />
| .Base || The cumulative result of any dice rolled in the Roll Text (Numeric modifiers are not included) <br />
|-<br />
| .Ones || The number of dice in the roll that came up as 1s <br />
|-<br />
| .Aces || The number of dice in the roll that came up as the maximum number on the die <br />
|-<br />
| .Odds || The number of dice in the roll that came up with an odd number <br />
|-<br />
| .Evens || The number of dice in the roll that came up with an even number <br />
|-<br />
| .RollText || The raw text of the roll that was use to generate the results <br />
|-<br />
| .Text || A text representation of the results of the roll, including the numbers rolled for each die <br />
|-<br />
| .tableEntryText || The text portion of the result of a table roll<br />
|-<br />
| .tableEntryImgURL || The image source portion of the result of a table roll<br />
|-<br />
| .tableEntryValue || Numeric value of tableEntryText (via parseInt). If a non-numeric value, will be 0<br />
|-<br />
| .Raw || The total numeric result without any formatting, even if placed somewhere formatting would normally be done. <br />
|}<br />
<br />
Examples:<br />
<pre><br />
--+Total Damage|[$MissileDamage.Total] (roll was 1d4+1)<br />
--+Base Damage|[$MissileDamage.Base] (without the +1)<br />
--=Attack|1d20 + @{selected|strength_mod} [STR] + @{selected|pb} [PROF] + [$BlessBonus] [Bless]<br />
</pre><br />
<br />
In this case, 1d4 will be rolled and stored in “BlessBonus”, which can then be used in the Attack line.<br />
<br />
'''''Mathematical Functions in Roll Expressions '''''<br />
<br />
The ScriptCards roll parser works from left to right, always maintaining a current value and applying whatever comes next to the total. The following in-line functions to the roll parser. These are:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Expression !! Meaning<br />
|-<br />
| {ABS} || Absolute Value<br />
|-<br />
| {CEIL} || Ceiling value (round up to the next whole number)<br />
|-<br />
| {FLOOR} || Floor value (round down to the next whole number)<br />
|-<br />
| {ROUND} || Round value (round up if the decimal portion is greater than 0.5, otherwise round down)<br />
|-<br />
| {NEGATE} || Multiply the value by negative one.<br />
|-<br />
| {SQRT} || Take the square root of the running value. ('''''1.4.1+''''')<br />
|-<br />
| {SQUARE} || Square the running value. ('''''1.4.2+''''')<br />
|-<br />
| {CUBEROOT} || Take the cube root of the running value. ('''''1.4.2+''''')<br />
|-<br />
| {CUBE} || Cube the running value. ('''''1.4.2+''''')<br />
|-<br />
| {SIN} || Return the SIN of running value. ('''''1.4.2+''''')<br />
|-<br />
| {COS} || Return the COS of running value. ('''''1.4.2+''''')<br />
|-<br />
| {TAN} || Return the TAN of running value. ('''''1.4.2+''''')<br />
|-<br />
| {ASIN} || Return the ASIN of running value. ('''''1.4.2+''''')<br />
|-<br />
| {ACOS} || Return the ACOS of running value. ('''''1.4.2+''''')<br />
|-<br />
| {ATAN} || Return the ATAN of running value. ('''''1.4.2+''''')<br />
|}<br />
<br />
<br />
'''''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 <nowiki>[[ ]]</nowiki> 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.<br />
<br />
'''''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.<br />
<br />
'''Rolling on Rollable Tables'''<br />
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.<br />
<br />
''Roll Variable Lines do not produce output lines on the card.''<br />
<br />
=== String Variable Assignment (--&) ===<br />
<br />
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:<br />
<br />
<pre><br />
--&MyText|Hello<br />
</pre><br />
<br />
Here, we assign the text "Hello" to the string variable named MyText. You can also append text to a string variable by prefixing the content with a + sign:<br />
<br />
<pre><br />
--&MyText|+ World<br />
</pre><br />
<br />
If run after the statement above, MyText will now contain "Hello World".<br />
<br />
String variables can be referenced using the syntax [&variablename]<br />
<br />
=== Call API (--@) ===<br />
<br />
ScriptCards can use a Call API instruction to execute other API commands. The Tag contains the API 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 API command is executed.<br />
<br />
Examples:<br />
<pre><br />
--@eh|list<br />
--@alter|_target|@{target|token_id} _bar|3 _amount|-[$Damage]<br />
</pre><br />
<br />
In the first example above, the command <code>!eh list</code> will be executed, calling [[EncounterHelper]]. In the second, {{fpl|1216260/ AlterBars}} is called to modify a token's Bar 3 value.<br />
<br />
'''''Note:''''' When ScriptCards (or any API script) runs other API 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).<br />
<br />
See [[API:Script Index]] for more options.<br />
<br />
=== Branch Label (--:) ===<br />
<br />
A branch label defines a line in your code that can be reached by one of the branching instructions (<nowiki>--^</nowiki>, <nowiki>--></nowiki>, or <nowiki>--?</nowiki>). The Tag serves as the label name, and must be unique on the card.<br />
<br />
The vertical bar (|) separator must be present, but the content portion of the line is unused and can be treated as a comment.<br />
<br />
Examples:<br />
<pre><br />
--:MyLoop|<br />
--:CriticalHit|Will jump here if we roll a critical hit!<br />
</pre><br />
<br />
''A Branch Label line does not produce an output line on the card.''<br />
<br />
=== Branch (--^) === <br />
<br />
A Branch line 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.<br />
<br />
Examples:<br />
<pre><br />
--^MyLoop|Jumps to MyLoop<br />
--^SkipCrit|We didn't crit, so skip the Crit code<br />
</pre><br />
<br />
''A Branch line does not produce an output line on the card.''<br />
<br />
=== Call Procedure (-->) ===<br />
<br />
Similar to a branch, a Call Procedure (sometimes knows 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 (<nowiki>--<</nowiki>) 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 (;).<br />
<br />
Examples:<br />
<pre><br />
-->FixFormat|#3333FF;#999999<br />
</pre><br />
<br />
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%].<br />
<br />
=== Return (--<) ===<br />
<br />
A return instruction marks the end of a Gosub procedure. 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.<br />
<br />
Examples:<br />
<pre><br />
--<|<br />
--<|End of MySub<br />
</pre><br />
<br />
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.<br />
<br />
=== Conditional Statement (--?) ===<br />
<br />
A conditional statement contains some equation in the Tag that will be evaluated. '''''If any part of the comparison can/does contain a space, it needs to be surrounded by double quotes'''''<br />
<br />
Based on the true/false result of the evaluation, one of two execution paths will be taken. These execution paths are detailed in the content section of the statement. The "if true" path is specified first (directly after the vertical bar), and the "if false" path is specified after it, also separated by a vertical bar.<br />
<br />
Example:<br />
<pre><br />
--?[$AttackRoll.Total] -ge [$TargetAC]|Hit|Miss<br />
</pre><br />
<br />
'''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.'''<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Branch Format !! Meaning<br />
|-<br />
| Label || If just a label is specified, execution will branch to that label when the comparison is matched.<br />
|-<br />
| >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 <br />
|-<br />
| =VariableName || The roll variable "VariableName" will be assigned the value following a semicolon (ex: --?1 -eq 1|=Roll;1d20)<br />
|-<br />
| &VariableName || The string variable "VariableName" will be assigned the value following a semicolon (ex: --?1 -eq 1|&Result;Hit|&Result;Miss)<br />
|-<br />
| % or %! || The current for...next loop will perform the "next" action (%) or will break out (%!) <br />
|-<br />
| [ || Code block (see below)<br />
|}<br />
<br />
Examples:<br />
<pre><br />
--?[$AttackRoll.Base] -eq 20|CriticalHit<br />
--?[$AttackRoll.Base] -eq 1|>Fumble;@{selected|dexterity_mod}<br />
--?"@{target|npc_type}" -inc "undead"|&MonsterType;Undead|&MonsterType;Not Undead<br />
--?[$Attack.Total] >= [$ArmorClass]|>Hit|>Miss<br />
</pre><br />
<br />
In the first example, if the Base value of AttackRoll is a 20 (natural 20 on the die) execution will branch to the CriticalHit label.<br />
<br />
In the second example, 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%].<br />
<br />
The third example looks for the word "undead" in the npc_type attribute of the targeted character. If it exists in the text, the MonsterType string variable will be set to "Undead", otherwise it will be set to "Not Undead". <br />
<br />
The final example would call 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.<br />
<br />
''Text that does/may contain a space should be enclosed in double quotes.''<br />
<br />
The following comparison operators are available:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Comparator !! Meaning<br />
|-<br />
| -eq || Equal To <br />
|-<br />
| -eqi || Case insensitive Equal To <br />
|-<br />
| -ne || Not Equal To <br />
|-<br />
| -nei || Case insensitive Not Equal To <br />
|-<br />
| -gt || Greater Than <br />
|-<br />
| -ge || Greater Than or Equal To <br />
|-<br />
| -lt || Less Than <br />
|-<br />
| -le || Less Than or Equal To <br />
|-<br />
| -inc || Includes (text strings). <br />
|-<br />
| -ninc || Does Not Include (text strings). <br />
|}<br />
<br />
Multi-part conditionals are supported with -and and -or as separators. For example:<br />
<br />
<pre><br />
--?[$Attack.Total] -ge @{target|npc_ac} -and [$Attack.Base] -ne 20|HitButNotCrit<br />
</pre><br />
<br />
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):<br />
<br />
true AND false OR true<br />
<br />
Will be evaluated as true. The first two (true and false) will be false, but then false OR true will be true.<br />
<br />
Conversely:<br />
<br />
true or false and false<br />
<br />
Will be false, because the first true and false will evaluate to true, and then true and false will be false.<br />
<br />
'''CODE BLOCKS'''<br />
<br />
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.<br />
<br />
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:<br />
<br />
<pre><br />
!script {{<br />
--=Roll|1d2<br />
--+Roll|[$Roll]<br />
--?[$Roll.Total] -eq 2|[<br />
--&Value|Yep!<br />
--+|We are inside the TRUE portion of the block<br />
--]|[<br />
--&Value|Nope<br />
--+|We are inside the FALSE portion of the block<br />
--]|<br />
--+After|the blocks!<br />
--+Value|[&Value]<br />
}}<br />
</pre><br />
<br />
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 --]|. <br />
<br />
At this time, blocks cannot be nested, and can only be created as part of a conditional (--[ is not a valid statement type)<br />
<br />
''A conditional statement does not produce a line of output on the card.''<br />
<br />
=== Case Statement (--c) ===<br />
<br />
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 (:). Each match condition includes a branch label that will be used if the test value matches the item. 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:<br />
<br />
<pre><br />
!script {{<br />
--#title|Case Statement Testing<br />
--=Roll|1d4<br />
--C[$Roll.Total]|1:>One;[$Roll]|2:>Two;[$Roll]|3:>Three;[$Roll]|4:>Four;[$Roll]<br />
--X|<br />
<br />
--:One| --+Value|was One ([%1%]) --<|<br />
--:Two| --+Value|was Two ([%1%]) --<|<br />
--:Three| --+Value|was Three ([%1%]) --<|<br />
--:Four| --+Value|was Four ([%1%]) --<|<br />
}}<br />
</pre><br />
<br />
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 variable as a parameter.<br />
<br />
=== Save and Load (--s and --l) ===<br />
<br />
This statement pair is used to either store (--s) or load (--l) data from persistent storage. Items stored in persistent storage remain between card rolls and between Roll20 sessions. There are two types of data that can be stored: settings and roll variables. <br />
<br />
Examples:<br />
<br />
<pre><br />
--Ssettings|GreenStyle<br />
--Srollvariables|FirstCardVars<br />
</pre><br />
<br />
In this case, the tag for the statement determines what type of item is being saved (settings or rollvariables). When saving settings, all non-default settings are written to the named setting storage value. When Roll Variables are saved, all variables that currently exist will be saved to the named storage value.<br />
<br />
Loading stored items simply requires the same command with the --l statement type:<br />
<br />
<pre><br />
--Lsettings|GreenStyle<br />
--Lrollvariables|FirstCardVars<br />
</pre><br />
<br />
When loading settings, all stored settings will be applied to the current card settings. You can override settings by changing them after the load.<br />
<br />
When loading roll variables, the saved variables will be added to (or overwrite if they have the same name) any variables on the current card. This means it is safe to create roll variables before the load statement.<br />
<br />
'''Practical Uses'''<br />
The major intended use of persistent storage is for storing card formats for use in later scripts. For example, the following script:<br />
<br />
<pre><br />
!scriptcard {{<br />
--#titlecardbackground|#22CC22<br />
--#oddrowbackground|#cceecc<br />
--#evenrowbackground|#99ee99<br />
--Ssettings|@{selected|token_name}<br />
}}<br />
</pre><br />
<br />
Would save the titlecardbackground, oddrowbackground, and evenrowbackground settings to a saved list named after the selected token's name. When creating cards for that token to run later, you could include the line:<br />
<br />
<pre><br />
--Lsettings|@{selected|token_name}<br />
</pre><br />
<br />
To load all of the settings at once. By creating these setting sets for each character, you can specify a different color scheme for each character that can then be used in cards with a single formatting line.<br />
<br />
There is a supplemental ! command added to support saved settings:<br />
<br />
<pre><br />
!sc-liststoredsettings<br />
</pre><br />
<br />
Will produce a list of all stored setting names, with buttons to list the setting values stored in each group and a button to delete groups as needed.<br />
<br />
=== Visual Effects (--v) ===<br />
<br />
The --v statement can be used to create visual effects on the tabletop. The tag portion of the statement can be either "token" or "betweentokens". The content portion of the statement contains the required parameters for the effect generation, separated by spaces. If the effect is "none", no effect will be played. If any other value that doesn't match a Roll20 effect name will result in a burst-fire effect.<br />
<br />
For "token" effects, the parameters are the token id for the token the effect happens on, followed by the effect specifier.<br />
<br />
Example:<br />
<pre><br />
--vtoken|@{selected|token_id} burst-fire<br />
</pre><br />
<br />
For "betweentoken" effects, the parameters are the source token id, the target token id, and the effect specifier.<br />
<br />
Example:<br />
<pre><br />
--vbetweentokens|@{selected|token_id} @{target|token_id} beam-magic<br />
</pre><br />
<br />
'''''Version 1.2.8+'''''<br />
<br />
An additional effect specifier, "point" is available in 1.2.8+. This specifier allows you to create a visual effect at a designated X/Y pixel coordinate. Future updates will add custom-vfx support to this option. The parameters are the X and Y coordinates and the effect descriptor. As of version 1.2.9, you can also use custom effect specifiers with Point effects:<br />
<br />
<pre><br />
--vpoint|150 200 burst-fire<br />
</pre><br />
<br />
=== Echo to Chat (--e) ===<br />
<br />
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.<br />
<br />
Example:<br />
<pre><br />
--eThe Ghost|/em hovers around @{selected|character_name}... BOO!<br />
</pre><br />
<br />
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).<br />
<br />
'''''Whispering'''''<br />
<br />
You can use the echo statement to send a whisper, but there's a trick to it. If you execute this code here:<br />
<br />
<pre><br />
--eThe Ghost|/w ExamplePlayerName Boo.<br />
</pre><br />
<br />
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.<br />
<br />
So, in conclusion, it's best to use something like this when you're sending a whisper:<br />
<br />
<pre><br />
!script {{<br />
--#hidecard|1<br />
--&sender|The Ghost<br />
--&receiver|ExamplePlayerName<br />
--&message|Boo.<br />
--e[&sender]|/w [&receiver] [&message]<br />
--eScriptCards|/w gm **Whispered from [&sender] to [&receiver]:** [&message] <br />
}}<br />
</pre><br />
<br />
This will ensure that the message appears in your chat feed as well.<br />
<br />
=== Repeating Section Access (--R) ===<br />
<br />
ScriptCards (as of v0.0.13) supports accessing repeating section rows on a character sheet with the --R statement type. <br />
<br />
There are three basic commands you can use with --R, and they are specified by the tag used:<br />
<br />
<pre><br />
--Rfind|characterid;EntryName;SectionPrefix;SearchField<br />
</pre><br />
<br />
This is the most direct way to access a repeating section row. Supplying the character ID, followed by what you are looking for (Greatsword, for example), followed by the character sheet's section prefix (repeating_attack), followed by the field to check what you are searching for (atkname) will load the matching section (if found) into the script parsers memory. For example:<br />
<br />
<pre><br />
--Rfind|@{selected|character_id};Greatsword;repeating_attack;atkname<br />
</pre><br />
<br />
Will look at the character's "repeating_attack" section for an entry with an atkname value equal to "Greatsword". Similarly:<br />
<br />
<pre><br />
--Rfind|@{selected|character_id};Bite;repeating_npcaction;name<br />
</pre><br />
<br />
Will look for a "Bite" action on an NPC's action list.<br />
<br />
<pre><br />
--Rfirst|characterid;section prefix<br />
</pre><br />
<br />
This form of the --R command will look at all of the entries in the specified repeating section and load the first one into memory:<br />
<br />
<pre><br />
--Rfirst|@{selected|character_id};repeating_attack<br />
</pre><br />
<br />
Would load the character's first "repeating_attack" row into memory.<br />
<br />
<pre><br />
--Rnext|<br />
</pre><br />
<br />
No parameters are required for --Rnext, which loads the next entry in the list that was obtained with "first" into memory.<br />
<br />
However a row is obtained, it will be parsed to replace any attribute references (ie, @{level}) with the corresponding character attribute.<br />
<br />
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".<br />
<br />
You can reference repeating attribute data using the syntax [*R:attributename] syntax (similar to referencing standard character attributes).<br />
<br />
Here are some examples:<br />
<br />
Display the details of the "Greatsword" PC attack:<br />
<br />
<pre><br />
!script {{<br />
--Rfind|@{selected|character_id};Greatsword;repeating_attack;atkname<br />
--+Attack Name|[*R:atkname]<br />
--+Base Damage|[*R:dmgbase]<br />
}}<br />
</pre><br />
<br />
[[File:Scriptcards repeating greatsword.png|Repeating Greatsword Attack]]<br />
<br />
List all of the actions an NPC can take (just actions, not legendary, etc.)<br />
<br />
<pre><br />
!script {{<br />
--#title|NPC Actions<br />
--#leftsub|@{selected|token_name}<br />
--Rfirst|@{selected|character_id};repeating_npcaction<br />
--:DisplayLoop|<br />
--?"[*R:name]" -eq NoRepeatingAttributeLoaded|Done<br />
--+Action:|[*R:name] [*R:attack_damage] [*R:attack_damagetype]<br />
--?"[*R:attack_damage2]" -eq ""|NoSecondaryDamage<br />
--+ |[*R:attack_damage2] [*R:attack_damagetype2]<br />
--:NoSecondaryDamage|<br />
--Rnext|<br />
-->DisplayLoop| <br />
--:Done|<br />
}}<br />
</pre><br />
<br />
[[File:Scriptcards repeating npcactions.png]]<br />
<br />
In the script above, we get the "first" repeating_npcaction and display information about it. We then execute "next" and repeat until we run into "NoRepeatingAttributeLoaded".<br />
<br />
'''''Special debugging command: dump'''''<br />
<pre><br />
--Rdump|<br />
</pre><br />
<br />
The "dump" command will list all of the attributes ScriptCards knows about for the currently loaded repeating row to the API Console Log.<br />
<br />
=== Assign Variable to Built-In Function (--~) ===<br />
<br />
ScriptCards has the ability to run a function built into the API script and return the results to a variable. Some functions return roll variables, while others return strings. See the function table below for details. The format is:<br />
<br />
--~VariableName|function;param1;param2;param3;...<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Function Name !! Parameters !! Description<br />
|-<br />
| distance || token_A_ID;token_B_ID || Calculate the Chebyshev distance in grid units between two tokens. This is the measurement scheme D&D 4E/5E use for diagonal distance measurement<br />
|-<br />
| euclideandistance || token_A_ID;token_B_ID || Calculate the Euclidean distance between two tokens. This is essentially the Pythagorean theorem in action. Returns the result in grid units.<br />
|-<br />
| euclideanpixel || token_A_ID;token_B_ID || Calculate the Euclidean distance between two tokens and returns the result is pixels instead of grid units. <br />
|-<br />
| euclideanlong || token_A_ID;token_B_ID || 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 is calculated instead of before. More accurate over long distances. <br />
|-<br />
| manhattandistance || token_A_ID;token_B_ID || Also called "taxicabdistance" (which is an acceptable function name), this measures to how-many-over, how-many-up/down distance, disallowing diagonal movement.<br />
|-<br />
| getselected || none || 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 the first selected token, VariableName2 the second, etc.<br />
|}<br />
<br />
'''''Functions with Sub Functions'''''<br />
<br />
Most ScriptCards functions are grouped into set as sub functions. The table below lists the major functions and their sub functions.<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Function Name !! Sub Function !! Parameters !! Return Type !! Description<br />
|-<br />
| array || define || arrayname;value1;value2;... || none || Creates an array called "arrayname" and adds value1, value2, etc. to the array<br />
|-<br />
| array || sort || arrayname || none || Sorts the specified array in place in ascending order<br />
|-<br />
| array || add || arrayname;value1;value2;... || none || Adds value1, value2, ... to the existing array "arrayname"<br />
|-<br />
| array || remove || arrayname;value1;value2;... || none || Removes value1, value2, ... from the existing array "arrayname". Resets the array index to 0.<br />
|-<br />
| array || replace || arrayname;currentvalue;newvalue || none || Replaces all occurrences of "currentvalue" in "arayname" with "newvalue"<br />
|-<br />
| array || setatindex || arrayname;index;newvalue || none || Replaces the array item at index "index" with "newvalue"<br />
|-<br />
| array || getindex || arrayname || stringVariable || Retrieves the current index in "arrayname" and stores it in the supplied string variable<br />
|-<br />
| array || setindex || arrayname;newindex || none || Sets the current index in array "arrayname" to "newindex"<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| array || removeat || arrayname;indexposition || none || Removes the item at index "indexposition" from "arrayname". Resets the current array index to 0.<br />
|-<br />
| array || indexof || arrayname;searchvalue || stringVariable || Searches the array "arrayname" for and item with the value of "searchvalue" and, if found, returns the index of the first matching value or "ArrayError" if not found<br />
|-<br />
| array || getlength || arrayname || stringVariable || Returns the number of items in array "arrayname"<br />
|-<br />
| array || pagetokens || arrayname;tokenid;(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. 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.)<br />
|-<br />
| 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.<br />
|-<br />
| array || stringify || arrayname || stringVariable || Returns all of the items in "arrayname" as a string separated by semicolons (;)<br />
|-<br />
| array || fromstring || arrayname || delimiter;string || Creates an array from "string", splitting "string" on "delimiter" to separate the items<br />
|-<br />
| array || statusmarkers|| arrayname;tokenid || none|| Creates an array (arrayname) of the active statusmarkers (sometimes called Token Markers) for the specified tokenid<br />
|-<br />
| math || angle || math;angle;tokenid;tokenid|| rollVariable || Calculates the angle between two tokens and returns the value in degrees<br />
|-<br />
| math || ceil || math;ceil;value || rollVariable || Rounds '''value''' up to the next integer, dropping any decimal portion of the number<br />
|-<br />
| math || clamp || math;clamp;value;lowerBound;upperBound || rollVariable || Returns '''value''', but restricted to the range of '''loweBound''' and '''upperBound'''.<br />
|-<br />
| math || floor || math;floor;value || rollVariable || Rounds '''value''' down, dropping any decimal portion of the number<br />
|-<br />
| math || max || math;max;valueA;valueB || rollVariable || Returns the larger of '''valueA''' vs '''valueB'''<br />
|-<br />
| math || min || math;min;valueA;valueB || rollVariable || Returns the smaller of '''valueA''' vs '''valueB'''<br />
|-<br />
| math || round || math;round;value || rollVariable || Rounds '''value''' to the nearest integer<br />
|-<br />
| string || length || string;length;stringValue || rollVariable || Returns the length of '''stringValue''' in characters<br />
|-<br />
| string || before || string;before;searchText;stringValue || stringVariable || Searches '''stringValue''' for '''searchText''' and returns the portion of '''stringValue''' prior to that text<br />
|-<br />
| string || after || string;after;searchText;stringValue || stringVariable || Searches '''stringValue''' for '''searchText''' and returns the portion of '''stringValue''' after that text<br />
|-<br />
| string || left || string;left;count;stringValue || stringVariable || Returns the leftmost '''count''' characters of '''stringValue'''<br />
|-<br />
| string || right || string;right;count;stringValue || stringVariable || Returns the rightmost '''count''' characters of '''stringValue'''<br />
|-<br />
| string || replace || string;replace;searchText;replaceText;stringValue || stringVariable || Replaces '''searchText''' in '''stringValue''' with '''replaceText''' and returns the resulting string<br />
|-<br />
| string || replaceall || string;replace;searchText;replaceText;stringValue || stringVariable || Replaces all intances of '''searchText''' in '''stringValue''' with '''replaceText''' and returns the resulting string '''''Requires 1.2.9+'''''<br />
|-<br />
| string || trim || string;trim;stringValue || stringVariable || Removes leading and trailing spaces from stringValue and returns the result. <br />
|-<br />
| string || substring || string;substring;start;count;stringValue || stringVariable || Returns '''count''' characters starting at '''start''' from '''stringValue'''<br />
|-<br />
| 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.<br />
|-<br />
| string || tolowercase || string;tolowercase;stringValue || stringVariable || Converts the passed string to lower case and assigns to the passed variable name. <br />
|-<br />
| string || touppercase || string || stringVariable || Converts the passed string to upper case and assigns to the passed variable name. <br />
|-<br />
| 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. <br />
|-<br />
| 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.<br />
|-<br />
| 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'''.<br />
|-<br />
| turnorder || clear || none || none || Clears all entries from the {{Turn Tracker}}/Initiative<br />
|-<br />
| turnorder || addtoken || tokenid;trackervalue || none || Adds the token represented by "tokenid" to the initiative tracker with an initiavie value of "trackervalue"<br />
|-<br />
| turnorder || replacetoken || tokenid;trackervalue || none || Replaces the token represented by "tokenid" in the initiative tracker with an initiavie value of "trackervalue". Will add the token if it doesn't exist in the tracker.<br />
|-<br />
| turnorder || removetoken || tokenid || none || Removes the token represented by "tokenid" from the initiative tracker if it exists<br />
|-<br />
| turnorder || addcustom || textlabel;trackervalue || none || Add a custom text entry to the {{Turn Tracker}}/Initiative named "textlabel" with an initiative value of "trackervalue"<br />
|-<br />
| system || date || getdatetime || stringVariable || Returns the date time in the active timezone (see settings) <br />
|-<br />
| system || date || getdate || stringVariable || Returns the date in the active timezone (see settings) <br />
|-<br />
| system || date || gettime || stringVariable || Returns the time in the active timezone (see settings)<br />
|-<br />
| system || dumpvariables || "rolls", "string", or "array" || none || Dumps all of the defined variables of the indicated type to the console log<br />
|-<br />
| system || findability || system;findability;charactername;abilityname || stringVariable || Returns the object ID of the ability on the indicated character or "AbilityNotFound"<br />
|-<br />
|}<br />
<br />
Examples:<br />
<br />
<pre><br />
--~HowFarAway|distance;@{selected|token_id};@{target|token_id}<br />
</pre><br />
<br />
Returns the distance (Chebyshev) between the selected and target tokens and stores it in "HowFarAway".<br />
<br />
<pre><br />
--SelectedDudes|getselected<br />
</pre><br />
<br />
If 5 tokens were selected, 6 variables would be created: SelectedDudesCount (with a value of 5), SelectedDudes1, SelectedDudes2, SelectedDudes3, SelectedDudes4, SelectedDudes5.<br />
<br />
=== Information Request (--i) ===<br />
<br />
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.<br />
<br />
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.<br />
<br />
After the user has clicked the button and responded to the requests, ScriptCards will resume processing the script from where it left off.<br />
<br />
Here is an example “i” line:<br />
<br />
<pre><br />
--IScriptCards needs additional information to continue;Click to select a target and provide information|t;MyNewTarget;Missile1Target||q;MyNameIs;What is your name?<br />
</pre><br />
<br />
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.<br />
<br />
Supported information request types are “t” for target token, and “q” for query.<br />
<br />
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).<br />
<br />
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:<br />
<br />
<pre><br />
q;UserName;What is your name?|Fred|Bob|Sally|Nancy<br />
</pre><br />
<br />
Would have a dropdown menu with four choices.<br />
<br />
== Inline Formatting ==<br />
<br />
Inline formatting is processed on Direct Output lines only (--+ lines) and the following inline format markup is available:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Formatting Tags !! Description<br />
|-<br />
| [b]..[/b] || Bold the text between the markers <br />
|-<br />
| [i]..[/i] || Italicize the text between the markers <br />
|-<br />
| [u]..[/u] || Underline the text between the markers <br />
|-<br />
| [s]..[/s] || Strike-Thru the text between the markers <br />
|-<br />
| [c]..[/c] || Center alignment <br />
|-<br />
| [l]..[/l] || Left alignment <br />
|-<br />
| [r]..[/r] || Right alignment <br />
|-<br />
| [j]..[/j] || Full justification alignment <br />
|-<br />
| [#xxx]..[/#] or [#xxxxxx]..[/#] || Use a 3 or 6 digit hex code to colorize the text between the markers <br />
|-<br />
| [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, <code>[img width=128 height=128]</code> )<br />
|-<br />
| [button]caption::action[/button] || Create a button with the label "caption" that performs the action defined by "action". <br />
|-<br />
| [t] || Converted to HTML table tag. Text after the "t" will be included inside the tag (width, border, etc)<br />
|-<br />
| [/t] || Converted to HTML close table tag.<br />
|-<br />
| [tr] || Converted to HTML table row tag. Text after the "tr" will be included inside the tag<br />
|-<br />
| [/tr] || Converted to HTML close table row tag.<br />
|-<br />
| [td] || Converted to HTML table cell tag. Text after the "tr" will be included inside the tag<br />
|-<br />
| [/td] || Converted to HTML close table cell tag.<br />
|}<br />
<br />
== Variables ==<br />
<br />
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. While it is possible to assign both a string and a roll variable the same name, doing so will likely result in confusion when looking at the script later, so it is not recommended.<br />
<br />
String Variables are assigned with the --& statement and are referenced using [&variableName] notation.<br />
<br />
Roll Variables are assigned with the --= statement, and the assignment value is always processed by the ScriptCards Roll Processor (resolves dice rolls, etc.)<br />
<br />
There are a handful of variables assigned automatically when a ScriptCard is executed. These are all string variables, and are:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Variable !! Value<br />
|-<br />
| SendingPlayerID || Contains the object ID of the player that sent the macro<br />
|-<br />
| SendingPlayerName || Contains the display name of the player<br />
|-<br />
| SendingPlayerColor || Contains the color code associated with the player<br />
|-<br />
| SendingPlayerSpeakingAs || The contents of the "Speaking As" dropdown window<br />
|-<br />
| SendingPlayerIsGM || Contains 1 if the player is a GM, and 0 if the player is NOT a GM<br />
|}<br />
<br />
== Arrays ==<br />
<br />
Arrays are a special type of variable, and are managed by the function (<nowiki>--~</nowiki> command). All of the array function commands follow the same pattern:<br />
<br />
<pre>--~variableName|array;subcommand;arrayname;param1;param2;param3;...</pre><br />
<br />
Not all array commands return anything to "variableName". The function table above will specify the return type of the command if any.<br />
<br />
There are a couple of different ways to create an array:<br />
<br />
The '''define''' array subcommand creates (or recreates) an array and assigns it values - one for each included parameter after the array name. For example:<br />
<br />
<pre>--~|array;define;Fruits;mango;peach;strawberry;apricot;banana;apple</pre><br />
<br />
will create an array called '''Fruits''' with 6 elements in the order listed in the command (mango, peach, etc.)<br />
<br />
You can also use two other subcommands to create arrays based on tokens:<br />
<br />
<pre>--~Count|array;pagetokens;Everybondy;@{selected|token_id}</pre><br />
<br />
and<br />
<br />
<pre>--~Count|array;selectedtokens;Selected</pre><br />
<br />
In both cases, arrays of tokens will be created, and a string variable called "Count" will be set to the number of tokens in the array. The '''pagetokens''' command returns (by default) all of the tokens on the page that contains the token passed as the parameter after the array name. You can filter the tokens that "pagetokens" includes in the array by appending an optional parameter describing the type of token you are looking for:<br />
<br />
<pre>--~Count|array;pagetokens;Everybondy;@{selected|token_id};npc</pre><br />
<br />
Will return only tokens on the page that represent characters that do not have a ''controlledby'' parameter set. The available options are "all" (default), "char", "graphic", "pc", and "npc".<br />
<br />
The '''selectedtokens''' command returns an array with all of the tokens that were selected when the script was called.<br />
<br />
You can also use an arbitrary string to create an array, specifying a delimiter with the '''fromstring''' command:<br />
<br />
<pre><br />
--&names|Fred<br />
--&names|+,Sally<br />
--&names|+,Ted<br />
--&names|+,Joyce<br />
--~|array;fromstring;,;[&names]<br />
</pre><br />
<br />
The above example builds a comma-separated string and then uses "fromstring" to create an array with 4 elements from it, specifying the comma as the delimiter.<br />
<br />
Finally, you can use the '''statusmarkers''' command to create an array with one entry for each active status marker on a specified token:<br />
<br />
<pre>--~|array;statusmarkers;Conditions;@{selected|token_id}</pre><br />
<br />
will create an array with one entry for each status active on the selected token. The array elements will be the internal name of the status (if you are using custom status marker packs, the names will be specified in the marker pack).<br />
<br />
'''Traversing Arrays'''<br />
<br />
Each array keeps track of an internal index position (starting at 0). Several commands let you manage this index:<br />
<br />
*'''getindex''' returns the current index value<br />
*'''setindex''' sets the index to the specified location in the array<br />
*'''getlength''' returns the number of elements in the array<br />
*'''indexof''' returns the index location of the specified element<br />
<br />
Other commands let you retrieve values from the array:<br />
<br />
*'''getfirst''' sets the index to 0 and returns the value at that position<br />
*'''getnext''' advances the index by 1 and returns the new current value<br />
*'''getprevious''' reduces the index by 1 and returns the new current value<br />
*'''getlast''' sets the index to the last elements in the array and returns the new current value<br />
<br />
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.<br />
<br />
'''Manipulating Array Elements'''<br />
<br />
Several array commands deal with inserting, removing, and modifying elements:<br />
<br />
*'''add''' works just like define, except that it takes an existing array and adds elements to it based on the passed parameters<br />
*'''remove''' looks for items matching each passed parameter and removes them from the indicated array if they exist<br />
*'''removeat''' allows you to specify an index location in the array and remove the element at that position<br />
*'''replace''' searches an array for a value and replaces all occurrences of it with a new value (if found)<br />
*'''sort''' sorts the elements in the array in ascending order<br />
*'''strinfigy''' returns a string variable that includes each array element separated by semicolons (;) <br />
<br />
'''Referencing Array Elements'''<br />
<br />
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.<br />
<br />
<pre><br />
!script {{<br />
--~dummy|array;pagetokens;myarray;@{selected|token_id}<br />
--~count|array;getcount;myarray<br />
--+Total:|There are [&count] graphical objects on the page<br />
--~testvar|array;getfirst;myarray<br />
--:loop|<br />
--+Value|[*[&testvar]:character_name]<br />
--~testvar|array;getnext;myarray<br />
--?[&testvar] -ne ArrayError|loop<br />
--+Loop1|Is Done!<br />
}}<br />
</pre><br />
<br />
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:<br />
<br />
<pre><br />
!script {{<br />
--~dummy|array;pagetokens;myarray;@{selected|token_id}<br />
--~count|array;getcount;myarray<br />
--+Total:|There are [&count] graphical objects on the page<br />
--%loopCounter|1;[&count]<br />
--+Value|[*[@myarray([&loopCounter])]:character_name]<br />
--%|<br />
--+Loop|Is Done!<br />
}}<br />
</pre><br />
<br />
This line : <nowiki>--+Value|[*[@myarray([&loopCounter])]:character_name]</nowiki> uses [@arrayName(index)] format (inside a [*characterid:attribute] syntax) to perform the same task as running through the loop with the index.<br />
<br />
(Note: Additional examples are on the way...)<br />
<br />
== For...Next Loops ==<br />
<br />
For...Next loops in ScriptCards are supported with the with the --% statement type. A loop is defined by starting off with:<br />
<br />
<pre><br />
--%LoopCounter|<start>;<end>;[step]<br />
</pre><br />
<br />
The start and end values are required, while the step parameter is optional. If the step is omitted, it will be assumed to be 1. A string variable named after the line tag ("LoopCounter" in the case above) will be created and will hold the current iteration value for the loop. Here is a real example:<br />
<br />
<pre><br />
--%LoopCounter|1;10;1<br />
</pre><br />
<br />
This will begin a loop identified by "LoopCounter" that will start at 1, increasing by 1 each iteration (the step) until it has completed 10 executions.<br />
<br />
The "next" statement is simply <code>--%|</code>, with no tag or parameters. This indicates to ScriptCards that it should increment the counter and go back to the beginning of the loop. Extending the example above:<br />
<br />
<pre><br />
!script {{<br />
--%LoopCounter|1;10;1<br />
--=Roll|1d20<br />
--+Loop|Counter is [&LoopCounter], roll was [$Roll]<br />
--%|<br />
}}<br />
</pre><br />
<br />
The <code>--%!|</code> sequence will break out of the loop, no matter how many iterations are remaining.<br />
<br />
The % and %! character sequences can also be used as part of a 1.2.1+ non-branching conditional to continue or break the loop:<br />
<br />
<pre><br />
--?"X[&RollInto]X" -eq "XX"|%<br />
</pre><br />
<br />
In this example, if the string variable RollInfo is empty, the loop will return to the top and continue with the next iteration, while:<br />
<br />
<pre><br />
--?"X[&RollInto]X" -eq "XX"|%!<br />
</pre><br />
<br />
Would cause the whole loop to end if the condition were true.<br />
<br />
== Referencing ==<br />
<br />
=== Roll Variables===<br />
<br />
Roll Variables can be referenced from the content portion of any line type, and from the tag portion of conditional statements. The referenced value is replaced when the line is executed.<br />
<br />
There are several modifiers that can be used to reference parts of a roll:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Modifier !! Meaning<br />
|-<br />
| No modifier || In a Direct Output Line (<nowiki>--+</nowiki>), GM Output Line (<nowiki>--*</nowiki>), or String Assignement (<nowiki>--&</nowiki>), 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<br />
|-<br />
| .Total || The end result of the roll equation. Formatting rules for "No Modifier" apply based on line type. <br />
|-<br />
| .Raw || The total value of the roll variable without any formatting, no matter what kind of line the reference is used in.<br />
|-<br />
| .Base || The cumulative result of any dice rolled in the Roll Text (Numeric modifiers are not included) <br />
|-<br />
| .Ones || The number of dice in the roll that came up as 1s <br />
|-<br />
| .Aces || The number of dice in the roll that came up as the maximum number on the die <br />
|-<br />
| .Odds || The number of dice in the roll that came up with an odd number <br />
|-<br />
| .Evens || The number of dice in the roll that came up with an even number <br />
|-<br />
| .RollText || The raw text of the roll that was use to generate the results <br />
|-<br />
| .Text || A text representation of the results of the roll, including the numbers rolled for each die <br />
|-<br />
| .tableEntryText || The text portion of the result of a table roll<br />
|-<br />
| .tableEntryImgURL || The image source portion of the result of a table roll<br />
|-<br />
| .tableEntryValue || If the tableEntryText is purely numeric, will contain the numeric value<br />
|}<br />
<br />
=== String Variables ===<br />
<br />
To reference a string variable, use the notation [&variablename]. String variables can be referenced in direct output, roll variable assignment, and string variable assignment statements.<br />
<br />
=== Character/Token Attributes ===<br />
<br />
A character or token attribute can be referenced from content portion of any type of line and is substituted when the line is executed. The general format for referencing a character attribute is [*ID:attribute]. ID can be a token ID or a character ID (these start with a dash). Additionally if you have specified a sourceToken or targetToken, you can substitute "S" or "T" for the ID (for example [*S:npc_type] will retrieve the npc_type attribute from the source token.<br />
<br />
By default, all attribute references will be pulled from the '''''character''''' object that the ID represents (either directly or by being a Token ID that represents a character).<br />
<br />
Keep in mind, that if you want to access the "max" of a character attribute (for example, the max hit points), then you cannot trust the name that your roll20 character sheet shows you when you hover your mouse over the max hit points. For example, this reference will not work: [*S:hp_max]. Instead, you need to use this reference: [*S:hp^].<br />
<br />
If your ID refers to a token, token attributes can be accessed by preceding the attribute name with "t-", for example [*S:t-aura1_radius]. Supported token attributes are:<br />
<br />
{|<br />
| t-name || t-id || t-statusmarkers || t-bar1_value<br />
|-<br />
| t-bar1_max || t-bar2_value || t-bar2_max || t-bar3_value<br />
|-<br />
| t-bar3_max || t-top || t-left || t-width<br />
|-<br />
| t-height || t-rotation || t-layer || t-aura1_radius<br />
|-<br />
| t-aura1_color || t-aura2_radius || t-aura2_color || t-aura1_square<br />
|-<br />
| t-aura2_square || t-tint_color || t-light_radius || t-light_dimradius<br />
|-<br />
| t-light_angle || t-light_losangle || t-light_multiplier || t-light_otherplayers<br />
|-<br />
| t-light_hassight || t-flipv || t-fliph || t-controlledby<br />
|-<br />
| t-_cardid || t-_pageid || t-imgsrc || t-bar1_link<br />
|-<br />
| t-bar2_link || t-bar3_link || t-represents || t-layer<br />
|-<br />
| t-isdrawing || t-name || t-gmnotes || t-showname<br />
|-<br />
| t-showplayers_name || t-showplayers_bar1 || t-showplayers_bar2 || t-showplayers_bar3<br />
|-<br />
| t-showplayers_aura1 || t-showplayers_aura2 || t-playersedit_name || t-playersedit_bar1<br />
|-<br />
| t-playersedit_bar2 || t-playersedit_bar3 || t-playersedit_aura1 || t-playersedit_aura2<br />
|-<br />
| t-lastmove || t-adv_fow_view_distance || t-has_bright_light_vision || t-has_night_vision<br />
|-<br />
| t-night_vision_distance || t-emits_bright_light || t-bright_light_distance || t-emits_low_light<br />
|-<br />
| t-low_light_distance || t-has_limit_field_of_vision || t-limit_field_of_vision_center || t-limit_field_of_vision_total<br />
|-<br />
| t-has_limit_field_of_night_vision || t-limit_field_of_night_vision_center || t-limit_field_of_night_vision_total || t-has_directional_bright_light<br />
|-<br />
| t-directional_bright_light_center || t-directional_bright_light_total || t-has_directional_dim_light || t-directional_dim_light_center<br />
|-<br />
| t-directional_dim_light_total || t-lightColor || || |<br />
|}<br />
<br />
'''''It is important to note that some attributes names on tokens have corresponding attribute names on characters, which represent different values. For example, [*T:id] returns the character ID, while [*T:t-id] returns the token ID.'''''<br />
<br />
=== Subroutine Parameters ===<br />
<br />
When using a gosub statement (-->) or a conditional marked as a gosub (prefixing the label with a > character), you can pass any number of parameters separated by semicolons (;) that the code in the subroutine can utilize.<br />
<br />
Subroutine parameters are numbered starting at 1, and are accessed by using the notation [%number%], so the first parameter is [%1%], the second is [%2%], etc.<br />
<br />
Parameter substitution happens on all line types, and happens prior to character attribute references or roll variable substitution.<br />
<br />
=== Campaign Attribute ===<br />
You can retrieve properties of the API's Campaign object with the [*C:attributename] syntax. For example, [*C:playerpageid] will retrieve the current player ribbon page from the Campaign object.<br />
<br />
=== Page Attributes ===<br />
If you have set the '''activepage''' parameter, you can retrieve page-related properties with the [*P:attributename] syntax, including the page's UDL parameters.<br />
<br />
=== Repeating Section Values ===<br />
<br />
You can reference repeating attribute data using the syntax [*R:attributename] syntax (similar to referencing standard character attributes). The currently active repeating row information will be used to retrieve attribute values. You can also retrieve the full attribute name for a repeating row attribute by using the [*R>attributename] notation. This is useful to pass to things like chatsetattr.<br />
<br />
=== Array Elements ===<br />
After an array has been declared, the elements can be referenced with [@arrayName(index)]. Array indices start at 0.<br />
<br />
== Deferred Resolution for Meta Scripts ==<br />
<br />
As of 1.2.9, ScriptCards supports a deferral character for use when calling another API script with via the --@ statement, to defer processing of meta script references so they get processed prior to the sub-API call insted of prior to ScriptCards execution. To defer this processing for meta script (SelectManager, Fetch) by inserting a deferral character into the meta call. For example, if I want to have ScriptCards call TokenMod as if the token for "Quej Gr'stra" (yes, I let Roll20 name my test NPCs) I could use something like this:<br />
<br />
--@token-mod|{^& select Quej Gr'stra} _on showname<br />
<br />
The "^" in between { and & will prevent SelectManager from seeing the call when the ScriptCard script is processed, but the --@ statement will remove the deferral character so the command that will be sent by ScriptCards is:<br />
<br />
!token-mod {& select Quej Gr'stra} --on showname<br />
<br />
With the deferral character removed, SelectManager will see the {& select ...} and do its magic.<br />
<br />
While the default deferral character is "^", the deferral character is a setting that can be changed:<br />
<br />
--#deferralcharacter|%<br />
<br />
Will make % the deferral character for future --@ statements in the running script.<br />
<br />
There are currently three supported Meta script structures: {^&...} for SelectManager, @^(...) and *^(...) for fetch, where the ^ in the structures here represents the placement of the deferral character.<br />
<br />
== Arrays ==<br />
<br />
Arrays are a new data type introduced in version 1.1.12 of ScriptCards, and are manipulated with associated function (--~) commands.<br />
<br />
* Arrays are a lists of strings. Items in an array cannot contain the semi-colon (;) character, as that is used to separate parameters in the function code that deals with arrays.<br />
* Arrays are accessed via the --~ script command. In some cases, the value of the tag (variable name) for array commands is not used, and can be a dummy value or simply omitted. I have omitted them in the statements below.<br />
* All commands that DO return a value return string values, even if the content is numeric.<br />
* If a command returns a value and there is some sort of reason that it isn't an array value, you will get "ArrayError" in the return value. This can happen if you reach the end of an array while stepping through it, for example, so checking for "ArrayError" can serve as the end condition for a loop.<br />
* Each array keeps track of its current index, allowing you to step forward and backwards through arrays.<br />
* Any number of arrays can be defined.<br />
* Unlike string variables and roll variables, array variables cannot (currently) be referenced directly. It is necessary to use the function (--~) syntax to manipulate arrays and get values from them as strings for use in other parts of your script.<br />
<br />
<br />
== Reentrant Scripts ==<br />
<br />
Reentrant scripts allow you to create buttons in your script code that will re-execute the script at a given label within the code. If you set the reentrant setting (--#reentrant|somevalue) to a non-zero value, your setting and variable information will be preserved between executions. Reentrant script can be used to present menus or choices and then continue acting.<br />
<br />
Reentrant buttons are created with the [rbutton]Caption::ReentryLabel;Parameter[/rbutton] construct. The caption will be displayed on the generated button. ReentryLabel is the name of a label in your script that the button will jump to when clicked, and Parameter will be passed in as a string value called "reentryval".<br />
<br />
Example:<br />
<pre><br />
!script {{<br />
--#reentrant|testing<br />
--=Roll|1d20<br />
--+Roll|[$Roll]<br />
--&String|That was a [$Roll.Raw]!<br />
--~x|array;define;MyArray;Apple;Banana;Orange<br />
--+Try it|[rbutton]Hello!::EXEC_PC_SPELL;9[/rbutton]<br />
--X|<br />
<br />
--:EXEC_PC_SPELL|<br />
--+ReentryVal|[&reentryval]<br />
--+The value of Roll is|[$Roll]<br />
--+Value of String|[&String]<br />
--+Array|[@MyArray(0)]<br />
--X|<br />
}}<br />
</pre><br />
<br />
This script sets up some variables and then displays a button labeled "Hello!". If the user clicks the button, the script will be re-entered starting at the "EXEC_PC_SPELL", which will display the content of the variables from the original execution.<br />
<br />
'''''Note: This section needs to be expanded upon'''''<br />
<br />
== Procedure Libraries ==<br />
<br />
You can now create handouts in your game in Roll 20 with the name format "ScriptCards Library NAME", where name is a name you assign to the library. Library names are case sensitive. It is my hope that the more proficient ScriptCards scripters out there will provide procedure libraries (or procedures that can be included in libraries) for others to use to make their scripting life easier. Be they specific to a game system, or to a type of activity, I think a robust set of libraries that GMs could use to enhance their scripting capabilities would be very valuable to the community. Should such things begin to emerge, I’ll create a portion of the ScriptCards Wiki page to house them.<br />
<br />
To include one or more libraries in a script, use the +++libname+++ directive (does not need a -- line associated with it). Multiple library names can be specified by separating them with semicolons (i.e., +++General;dnd5elib;Colorize+++ would include three libraries (General, dnd5elib, and Colorize).<br />
<br />
Included libraries are separated from the main script code by the automatic inclusion of "--X|" before the first library is appended to the script, and all libraries are loaded at the end of the script before script processing takes place.<br />
<br />
Procedures and labels in libraries can be used just as if they were included in the body of your script. Note that this DOES mean that you could, technically, jump into a library with a direct branch (--^) or direct branch conditional, but I recommend using libraries to store reusable procedures.<br />
The Notes section of the library handout stores the library code, and is written just like any other ScriptCards code except:<br />
<br />
* They cannot use roll queries (?{Some Prompt:}) to get information from the user at execution time.<br />
* They cannot use @{} notation to access character and token information.<br />
<br />
Both of these limitation stem from the fact that Procedure Libraries are not processed by the chat server, which is what handles these items.<br />
<br />
Here is an example of handling damage modifications (resistance, vulnerability, and immunity) in D&D 5E with a library:<br />
<br />
<pre><br />
!script {{<br />
+++dnd5elib+++<br />
--#|Damage Modifiers Test<br />
--#targettoken|@{target|token_id}<br />
-->Lib5E_CheckDamageModifiers|ResistType;fire<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] fire damage<br />
<br />
-->Lib5E_CheckDamageModifiers|ResistType;cold<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] cold damage<br />
<br />
-->Lib5E_CheckDamageModifiers|ResistType;poison<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] poison damage<br />
<br />
-->Lib5E_CheckDamageModifiers|ResistType;acid<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] acid damage<br />
<br />
--X|<br />
}}<br />
</pre><br />
<br />
Library content (In a handout called “ScriptCards Library dnd5elib” NOTE: Paste into Notepad first and then paste into the handout in Roll20 to avoid bringing over HTML formatting from the web site):<br />
<br />
<pre><br />
--/|ScriptCards Library: dnd5elib version 0.0.1<br />
--/|Provides various utility procedures for D&D 5E games<br />
<br />
--/|Lib5E_CheckDamageModifiers handle damage resistance, vulnerability, and immunity. <br />
--/|Pass a string variable to be filled with a string to be appended to a dice roll and the damage type <br />
<br />
--:Lib5E_CheckDamageModifiers|damageVariableName;damageType<br />
--&[%1%]|<br />
--?"[*T:npc_vulnerabilities]" -inc "[%2%]"|>_Lib5E_IsVulnerable;[%1%]<br />
--?"[*T:npc_resistances]" -inc "[%2%]"|>_Lib5E_IsResistant;[%1%]<br />
--?"[*T:npc_immunities]" -inc "[%2%]"|>_Lib5E_IsImmune;[%1%]<br />
--<|<br />
<br />
--:_Lib5E_IsVulnerable| --&[%1%]| * 2 [Vulnerable] --<|<br />
--:_Lib5E_IsResistant| --&[%1%]| \ 2 [Resistant] --<|<br />
--:_Lib5E_IsImmune| --&[%1%]| * 0 [Immune] --<|<br />
</pre><br />
<br />
The idea is that the functions in the library create a string that can be appended to a roll to modify the output based on resistances, so you pass Lib5E_CheckDamageModifiers the name of the string variable you want to use and the damage type. The variable (ResistType in this case) will include either nothing, “* 2 [Vulnerable]”, “\ 2 [Resistant]”, or “* 0 [Immune]” which can be included in a roll assignment (--=) to modify the damage as appropriate. The order here might be important if an NPC is misconfigured to be both resistant and immune to the same damage type. Since immune is an absolute, having it last ensures that it will override resistant or vulnerable. A creature that is both vulnerable and resistant (again, misconfigured) will come back as resistant since that condition is checked after vulnerable.<br />
Some notes: I prefix my library labels with either “Lib5E_” or “_Lib5E_” as a clarity convention. This isn’t strictly necessary but you should be aware that if two libraries (or if your script and a library) define the same label, the last label defined will win. Since libraries are appended to the end of the script in the order you include them in the +++libname+++ directive, you can somewhat control this, but it is probably best to avoid re-declaring labels. <br />
<br />
In my case, items beginning with “Lib5E_” are intended to be called by scripts, while items beginning with “_Lib5E_” are intended to be used as subroutines by the “public” procedures. Of course, there is no reason you couldn’t call them directly.<br />
<br />
You might also note that I’ve included some library information in comment lines (--/|) at the top of the library. These are ignored by ScriptCards, and are a good way to convey requirements, parameters, usage information, etc.<br />
<br />
== Example Libraries ==<br />
<br />
=== dnd5elib ===<br />
<br />
[https://github.com/kjaegers/ScriptCards Download the dnd5elib Library from the ScriptCards GitHub]<br />
<br />
The '''dnd5elib''' library provides a collection of utility procedures that help simplify dealing with the D&D 5E Official Sheet. Some of the procedures in this library require '''chatsetattr''' to be installed in your game. This is a growing library, and currently only has a handful of routines. They are:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Procedure Name !! Notes<br />
|-<br />
| style="white-space:nowrap" | Lib5E_CheckDamageModifiers || This procedure can be used to evaluate vulnerabilities, resistances, and invulnerabilities on an NPC. After setting the --#target| parameters, pass the Lib5E_CheckDamageModifiers procedure a variable name (no reference information) and a damage type (i.e., fire, cold, bludgeoning, etc.) and a string variable with the name passed in as the first parameter will be created that contains text that can be included in a roll line (--=) in order to modify the roll as appropriate. For example, '''-->Lib5E_CheckDamageModifiers|ResistType;fire''' will check the current target character's attributes for "fire" and will either return an empty string (no references), "* 0 [Immune]" if the creature is immune, "\ 2 [Resistant]" if the creature is resistant, or "* 2 [Vulnerable]" if the creature is vulnerable to fire damage.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_DeductSpellSlot || Pass in a character_id and a slot level, and the script will expend one spell slot of that level, capping the value at 0 slots remaining. For Example '''<nowiki>-->Lib5E_DeductSpellSlot|@{selected|character_id};1</nowiki>''' to deduct a first level spell slot from the selected character.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_FindResource || Used to locate a resource value on a character. Pass in a character_id, a resource name, and two variable names. The procedure will check both repeating and non-repeating resources looking for a resource whose name matches what was passed in and return three variables. The first will be a string variable named for the 3rd parameter and contains the attribute name of the resource's "name" field. The second will be a string variable named after parameter 4 and contains the resource's value field attribute name, and the third variable is a Roll Variable, also named after the 4th parameter that contains the current resource value. Example: '''<nowiki>-->Lib5E_FindResource|@{selected|character_id};Crossbow bolts;ResName;ResValue</nowiki>''' will find "Crossbow bolts" as a resource on the character and return [&ResName] which is the name of the resource attribute, [&ResValue] which is the '''name of the attribute that stores the value''' and [$ResValue] which is the current numeric value of the resource.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Global_Attack_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Attack Modifiers (repeating_tohitmod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Bless" for 1d4 active and "Being Cool" for +2 active, I will get a return string " + 1d4 [Bless] + 2 [Being Cool]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Save_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Save Modifiers (repeating_savemod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Bless" for 1d4 active and "Being Cool" for +2 active, I will get a return string " + 1d4 [Bless] + 2 [Being Cool]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Skill_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Skill Modifiers (repeating_skillmod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Guidance" for 1d4 active and "Being Cool" for +2 active, I will get a return string " + 1d4 [Guidance] + 2 [Being Cool]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_AC_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Save Modifiers (repeating_savemod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Shield of Faith" with a value of 2 active, I will get a return string " + 2 [Shield of Faith]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Damage_Modifiers || Pass a character ID and TWO string variable to set the return value. The first string will be for normal damage, and the second will be the additional damage on a crit. This procedure will look through the Global Damage Modifiers (repeating_damagemod_*) for rows that are active (checked on the character sheet) and return two strings with the dice rolls and descriptions for them (for example, if I have "Sneak Attack" with a value of 1d6 normal and 1d6 critical damage active, I will get a return string " + 1d6 [Sneak Attack]" and another string of " + 1d6 [Sneak Attack CRIT]" that can be used in a dice rolls.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_DivineSmiteDice || Used to calculate the number of dice to be rolled for a paladin's Divine Smite. Pass a target token id, a spell slot level, and a string variable to be set to the dice roll amount based on the NPC_TYPE attribute of the target token. The returned variable will contain a dice roll (like "3d8" that can be used in a --= line)<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Character_Summary || Outputs a mini character sheet, including clickable buttons for attacks, actions, legendary actions, etc. Will automatically detect a PC vs NPC and output the appropriate sections.<br />
|}<br />
<br />
Due to formatting issues with the Wiki, the library code has been moved to a [https://gist.github.com/kjaegers/52f6049ddd257f0a1288aca4bbde13c5 GITHUB GIT]. Please view the GIST in raw mode and copy the text and paste it into a handout called "ScriptCards Library dnd5elib" in your Roll20 Game.<br />
<br />
== What to Know if you are Coming from PowerCards ==<br />
<br />
''Note: This section is a work in progress.''<br />
<br />
While ScriptCards and PowerCard have very similar output goals, their internals and use are quite different. The table below summarizes some of the major differences between the scripts.<br />
<br />
::{| class="wikitable"<br />
|-<br />
! PowerCards !! ScriptCards <br />
|-<br />
| With a handful of exceptions, all lines in a PowerCard macro are intended to produce a line of output on the final card. || With ScriptCards, ONLY the <code>--+</code> and <code>--*</code> statement types produces output <br />
|-<br />
| PowerCards lines begin with two dashes (<code>--</code>) followed by a unique tag name for the line, followed by a vertical bar and the content for the line. || ScriptCards lines begin with two dashes (<code>--</code>) followed by a '''statement type identifier''', which is a single character that identifies the type of line to the interpreter. This is followed by a tag (frequently optional), a vertical bar, and the parameters for the statement being executed.<br />
|-<br />
| PowerCard macros are always processed top to bottom. Lines can be hidden so they don't output anything, but there is no looping or branching (--SkipTo looks like a branch, but it just hides all of the lines until the referenced label. || ScriptCards scripts support true branching, including direct branching (<code>--^</code>) and procedure branching (<code>--></code>) and (<code>--<</code>). Procedures support parameters and a call stack so procedures can be nested to call other procedures.<br />
|-<br />
| All lines in a PowerCards macro need to have unique tags because PowerCards builds the card as a single JavaScript object using the tag names to store what will be displayed. This is why repeated tag names always result in the last one being shown. || ScriptCards tags do not need to be unique, and in the case of many line types are optional.<br />
|-<br />
| PowerCards conditionals result in either showing or hiding the line they are on. || ScriptCards conditionals '''''only''''' support branching as the result of the comparison. This branching can be direct (a GOTO) or procedural (a GOSUB) '''''NOTE: As of version 1.2.0, ScriptCards also supports roll/string variable assignment as a result of conditional evaluation'''''<br />
|-<br />
| PowerCards relies on the Roll20 [[Quantum Roll]] server and inline rolls for all dice functions || ScriptCards includes its own dice roll parser, and '''''does not support''''' inline rolls.<br />
|-<br />
| PowerCards RollIDs (often mistaken for variables) are assigned by analyzing the results of an inline roll, and cannot be referenced in other rolls, so you can't roll a <code>1d4</code> and then roll a <code>1d20</code> and add the <code>1d4</code> result because all of the rolls happen on the chat server before PowerCards gets the macro text. || ScriptCards supports two types of variables: Roll Variables and String Variables. Because ScriptCards uses its own roll parser and is not dependent upon the chat server, rolls and their results can be used in other rolls, math functions, output, etc.<br />
|}<br />
<br />
== Example Scripts ==<br />
<br />
Below are some sample scripts that utilize the various statement types in ScriptCards:<br />
<br />
=== Divine Smite ===<br />
<br />
This script will prompt the user for a spell slot level to expend on a divine smite. It will check the target's npc_type to see if it is an Undead or Fiend, which adds an additional d8 to the smite roll.<br />
<br />
[[File:ScriptCards Divine Smite.png|Divine Smite Script Output]]<br />
<br />
<pre><br />
!scriptcard {{<br />
--#title|Divine Smite<br />
--=DiceCount|?{Spell Slot Level?|1|2|3|4|5|6|7|8|9} + 1<br />
--=IsFiendOrUndead|0<br />
--?"@{target|npc_type}" -inc fiend|>IsBoosted<br />
--?"@{target|npc_type}" -inc undead|>IsBoosted<br />
--=TotalDice|[$DiceCount] + [$IsFiendOrUndead]<br />
--=SmiteRoll|[$TotalDice]d8<br />
--#emoteText|@{selected|token_name} smites @{target|token_name}<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
--+Smite|deals [$SmiteRoll] radiant damage.<br />
--X|<br />
<br />
--:IsBoosted|<br />
--=IsFiendOrUndead|1<br />
--<|<br />
}}<br />
</pre><br />
<br />
==== How It Works ====<br />
<br />
The first line sets the "title" card parameter to "Divine Smite".<br />
<br />
Line 2 Shows a query to the user asking for the spell slot level, adds one and stores the value in the "DiceCount" Roll Variable. The query/dropdown is generated by the chat server prior to the script being executed.<br />
<br />
Line 3 defaults the "IsFiendOrUndead" Roll Variable to 0.<br />
<br />
Lines 4 and 5 compare the target's "npc_type" attribute (passed by the chat server as text) to see if they include either "undead" or "fiend". If true, the IsBoosted subroutine will be called. No parameters are passed to this subroutine.<br />
<br />
Line 6 sets the "TotalDice" variable to the base (DiceCount) number plus the IsFiendOrUndead number, which will be a 0 or a 1.<br />
<br />
Line 7 calculates "SmiteRoll" by rolling a number of d8 equal to the "TotalDice" value.<br />
<br />
Lines 8-10 set the parameters for the emote, which appears above the card content. By setting the sourceToken and the targetToken, their icons will appear in the emote surrounding the text describing the action.<br />
<br />
Line 11 is the only line that actually produces output on the card. It results in "Smite deals # radiant damage".<br />
<br />
Line 12 ends the script execution, preventing the script from continuing and running the subroutines out of context.<br />
<br />
Lines 14-16 are the IsBoosted subroutine, starting with the :IsBoosted label. The IsFiendOrUndead variable is set to 1, and a return from subroutine is executed.<br />
<br />
=== Magic Missile ===<br />
<br />
This script demonstrates using a loop and calling a subroutine to fire a number of missiles determine by the spell slot level used to cast the spell.<br />
<br />
[[File:ScriptCards_MagicMissile_Fixed.png|Magic Missile Script Output]]<br />
<br />
<pre><br />
!scriptcard {{ <br />
--#title|Magic Missile<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
--=MissileCount|?{Spell Slot Level?|1|2|3|4|5|6|7|8|9} + 2<br />
--=DisplayCount|1<br />
--=MissileDamage|0<br />
--#leftsub|Slot level ?{Spell Slot Level?}<br />
--#rightsub|Ranged Attack<br />
--#emoteText|Fred uses a level ?{Spell Slot Level?} spell slot to fire [$MissileCount.Total] missiles of magical force!<br />
--:MissileLoop|<br />
-->FireMissile|<br />
--=DisplayCount|[$DisplayCount] + 1<br />
--?[$DisplayCount] -le [$MissileCount]|MissileLoop<br />
--+Total|Total damage is [$MissileDamage]<br />
--X|<br />
<br />
--:FireMissile|<br />
--=ThisMissile|1d4 + 1<br />
--=MissileDamage|[$MissileDamage] + [$ThisMissile]<br />
--+Missile|[$DisplayCount.Total] Hits for [$ThisMissile] [b]force[/b] damage<br />
--<|<br />
}}<br />
</pre><br />
<br />
==== How It Works ====<br />
<br />
Lines 1-3 set the card title, the source token and the target token. Setting these tokens causes their icons/avatars to appear in the Emote section of the card.<br />
<br />
Line 4 asks the user what spell slot level they wish to use to cast magic missile. The number of missiles fired is equal to 2 plus the spell level, and this is stored in the MissileCount variable.<br />
<br />
Line 5 stores a 1 in the DisplayCount variable. This will be used to control the loop to determine the number of missiles fired and the missile number when displaying damage rolls.<br />
<br />
Line 6 initializes MissileDamage to 0<br />
<br />
Line 7 sets the left subtitle to the text "Slot Level #", where # is the spell slot level being used.<br />
<br />
Line 8 sets the right subtitle to the text "Ranged Attack".<br />
<br />
Line 9 sets the emoteText parameter with a description of the action, including the slot level and number of missiles fired.<br />
<br />
Line 10 is a label for the missile firing loop<br />
<br />
Line 11 Calls the "FireMissile" subroutine<br />
<br />
Line 12 increases the DisplayCount variable by 1<br />
<br />
Line 13 Checks to see if there are still missles to fire (DisplayCount <= MissileCount) and if so branches to MissileLoop<br />
<br />
Line 14 Displays the total damage dealt by the spell.<br />
<br />
Line 15 stops execution of the script to prevent out of context execution of the subroutine.<br />
<br />
Lines 76-21 are the FireMissile subroutine, beginning with the FireMissile label. The 1d4+1 is rolled and assigned to "ThisMissile". The result is added to the existing MissileDamage total, and a line for the current missile is displayed with the missile number and the damage for the missile.<br />
<br />
=== Longsword Attack ===<br />
<br />
This script demonstrates a standard 5E D&D melee weapon attack, including detection of misses, fumbles, hits, and critical hits. If installed, alterbars is used to decrement the target's BAR3 value by the damage dealt.<br />
<br />
[[File:ScriptCards Longsword.png|Longsword Script Output]]<br />
<br />
<pre><br />
!scriptcard {{<br />
--#title|Longsword<br />
--#leftsub|Melee Attack<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
--#emoteText|@{selected|token_name} attacks @{target|token_name}<br />
--=TargetAC|@{target|npc_ac}<br />
--?[$TargetAC.Total] -gt 0|DoneWithAC<br />
--=TargetAC|@{target|ac}<br />
--:DoneWithAC|<br />
--=AttackRoll|1d20 + @{selected|strength_mod} [STR] + @{selected|pb} [PROF]<br />
--+Attack|@{selected|token_name} rolls [$AttackRoll] vs AC [$TargetAC].<br />
--?[$AttackRoll.Base] -eq 20|Crit<br />
--?[$AttackRoll.Base] -eq 1|Fumble<br />
--?[$AttackRoll.Total] -ge [$TargetAC.Total]|Hit<br />
--+Miss|The attack missed.<br />
--^Final|<br />
<br />
--:Fumble|<br />
--+Fumble!|The attack went horribly wrong.<br />
--^Final|<br />
<br />
--:Hit|<br />
--=Damage|1d8 + @{selected|strength_mod} [STR]<br />
--+Hit!|The attack hit @{target|token_name} for [$Damage] slashing damage.<br />
--@alter|_target|@{target|token_id} _bar|3 _amount|-[$Damage]<br />
--^Final|<br />
<br />
--:Crit|<br />
--=Damage|1d8 + @{selected|strength_mod} [STR] + 1d8 [CRIT]<br />
--+Critical Hit!|The attack hit @{target|token_name} for [$Damage] slashing damage.<br />
--@alter|_target|@{target|token_id} _bar|3 _amount|-[$Damage]<br />
<br />
--:Final|<br />
}}<br />
</pre><br />
<br />
==== How it Works ====<br />
<br />
In lines 1-5, we set the title, subtitle, and emote text along with the tokens for the emote area.<br />
<br />
Lines 6-9 allow us to determine the AC of the target. On the 5E Roll20 sheet, NPCs armor class is stored in "npc_ac", while PCs armor class is in "ac". First we grab npc_ac and if it is zero, we check AC.<br />
<br />
Line 10 rolls the attack roll, rolling 1d20 and adding the attacker's strength modifier and proficiency bonus<br />
<br />
Line 11 displays the result of the attack roll on the card<br />
<br />
Lines 12-14 determine what kind of result the attack had. If the .Base value of the roll was 20, we branch to "Crit". If it was 1, we branch to "Fumble". If the .Total value of the roll was greater than or equal to the AC that was determined in Lines 6-9, we branch to Hit.<br />
<br />
Assuming we didn't branc anywhere, the result of the attack was a miss, so we display that on line 15 and then branch to "Final"<br />
<br />
This is followed by three branch segments, :Fumble, :Hit, and :Crit. A fumble displays a text message and branches to :Final.<br />
<br />
On a hit or a crit, we roll Damage (adding additional damage dice on a crit). We display a "Hit!" or "Critical Hit!" message and then make an API call to AlterBars, passing it the token id, bar we want to modify (3 in this case), and the amount we want to modify by the Damage value.<br />
<br />
=== Party Health Status ===<br />
<br />
This example calculates the current Hit Points remaining and HP percentage for each character and creates a color-coded display with the current party status.<br />
<br />
[[File:ScriptCards Party Health.png]]<br />
<br />
<pre><br />
!scriptcard {{<br />
--#title|Party Status<br />
--#titleCardBackground|#33CC33<br />
--#oddrowbackground|#bfee90<br />
--#evenrowbackground|#90eebf<br />
-->HealthCheck|@{Quej Grastra|character_id}<br />
-->HealthCheck|@{Brim Cheuto|character_id}<br />
-->HealthCheck|@{Odug Ututees|character_id}<br />
--X|End of card Execution<br />
<br />
--:HealthCheck|<br />
--=HealthPerc|[*[%1%]:hp] / [*[%1%]:hp^] * 100 \ 1<br />
--=HealthColor|000000<br />
--?[$HealthPerc.Total] -gt 50|HealthSkip<br />
--=HealthColor|FF0000<br />
--:HealthSkip|<br />
--+[*[%1%]:character_name]|has [#[$HealthColor.RollText]][*[%1%]:hp] of [*[%1%]:hp^][/#] HP [R]([$HealthPerc.Total]%)[/R]<br />
--<|End of HealthCheck<br />
}}<br />
</pre><br />
<br />
==== How it Works ====<br />
<br />
Lines 1-4, we set the card title, and set the title background and row background colors to shades of green.<br />
<br />
Lines 5-7 make gosub calls the the "HealthCheck" subroutine, passing in the character ID of each of the named characters (these are the names of the characters in my test game)<br />
<br />
Line 8 terminates the script execution.<br />
<br />
The remaining lines of the script are the HealthCheck subroutine, which works like this:<br />
<br />
Line 10 is the subroutine label (:HealthCheck)<br />
<br />
Line 11 uses the character id passed as a parameter and combines it with character attribute lookup *(...) to retrieve the value of "hp" and "hp<nowiki>^</nowiki>" for the character. The <nowiki>^</nowiki> character is used to specify that we want the MAX value for this attribute for the second call. We divide these two numbers and multiple by 100 to get a percentage. Finally, we use integer division by 1 to round the percentage and drop the decimals. The end result gets stored in the HealthPerc roll variable.<br />
<br />
Line 12 defaults to color of the health text to black<br />
<br />
Line 13 check to see if the health percentage is greater than 50. If so, it branches to HealthSkip, preventing the script from executing line 13.<br />
<br />
Line 14 sets the color of the health text to red<br />
<br />
Line 15 is the label that will be branched to from Line 13 to skip the red coloring<br />
<br />
Line 16 again uses character attribute substitution and the passed parameter value to output a display line containing the character name, the colorized health total, and the percentage value. The percentage is right-justified.<br />
<br />
Line 17 returns from the HealthCheck subroutine.<br />
<br />
=== Expanded Magic Missile Script ===<br />
<br />
This is the expanded and enhanced version of the Magic Missile script covered in {{yt|watch?v=u50xvNzS9Zk | this video}}. It includes visual and audio effects, checking and deducting spell slots, and applying damage using either Token-Mod or Alterbars.<br />
<br />
<pre><br />
!scriptcard {{ <br />
--#title|Magic Missile<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
<br />
-->GetAndCheckSlotInformation|<br />
<br />
--=MissileCount|[$SlotLevel] + 2<br />
--=DisplayCount|1<br />
--=MissileDamage|0<br />
--#leftsub|Slot level [$SlotLevel]<br />
--#rightsub|Ranged Attack<br />
--#emoteText|@{selected|character_name} uses a level [$SlotLevel.Total] spell slot to fire [$MissileCount.Total] missiles of magical force!<br />
<br />
--:MissileLoop|<br />
-->FireMissile|<br />
--=DisplayCount|[$DisplayCount] + 1<br />
--?[$DisplayCount] -le [$MissileCount]|MissileLoop<br />
--+Total|Total damage is [$MissileDamage]<br />
-->DeductSpellSlot|<br />
--#rightsub|Level [$SlotLevel] Left: [$SlotsRemaining] <br />
-->PlayEffects|none;burst-smoke;beam-magic;spell_01<br />
-->ApplyDamageTokenmod|@{target|token_id};3;-[$MissileDamage]<br />
-->ApplyDamageAlterbars|@{target|token_id};3;-[$MissileDamage]<br />
--X|<br />
<br />
--:FireMissile|<br />
--=ThisMissile|1d4 + 1<br />
--=MissileDamage|[$MissileDamage] + [$ThisMissile]<br />
--+Missile|[$DisplayCount.Total] Hits for [$ThisMissile] [b]force[/b] damage<br />
--<|<br />
<br />
--:GetAndCheckSlotInformation|<br />
--=SlotLevel|?{Spell Slot Level?|1|2|3|4|5|6|7|8|9}<br />
--=SlotsTotal|[*S:lvl[$SlotLevel]_slots_total]<br />
--=SlotsExpended|[*S:lvl[$SlotLevel]_slots_expended]<br />
--?[$SlotsExpended.Total] -ge [$SlotsTotal.Total]|NoSlotsLeft<br />
--<|<br />
<br />
--:NoSlotsLeft|<br />
--+|[*S:character_name] has no level [$SlotLevel.Total] spell slots available.<br />
--X|<br />
<br />
--:DeductSpellSlot|<br />
--=SlotsExpended|[$SlotsExpended] + 1<br />
--@setattr|_charid [*S:character_id] _lvl[$SlotLevel]_slots_expended|[$SlotsExpended] _silent<br />
--=SlotsRemaining|[$SlotsTotal] - [$SlotsExpended]<br />
--<|<br />
<br />
--:PlayEffects|Parameters are : source effect; target effect; line effect; sound effect<br />
--vtoken|@{selected|token_id} [%1%]<br />
--vtoken|@{target|token_id} [%2%]<br />
--vbetweentokens|@{selected|token_id} @{target|token_id} [%3%]<br />
--@roll20AM|_audio,play,nomenu|[%4%]<br />
--<|<br />
<br />
--:ApplyDamageTokenmod|Parameters are tokenid;bar#;amount<br />
--@token-mod|_ignore-selected _ids [%1%] _set bar[%2%]_value|[%3%]<br />
--<|<br />
<br />
--:ApplyDamageAlterbars|<br />
--@alter|_target|[%1%] _bar|[%2%] _amount|[%3%]<br />
--<|<br />
}}<br />
</pre><br />
<br />
[[Category:Featured articles]]</div>5004103https://wiki.roll20.net/Script:ScriptCardsScript:ScriptCards2021-09-28T16:59:28Z<p>5004103: /* Comment (--/) */</p>
<hr />
<div>{{revdate}}<br />
== Introduction ==<br />
'''ScriptCards''' provides a script interpreter that can be used to create powerful macros that display the results of player/NPC actions, or display other information in a pleasing visual format in your game's chat window. The scripting language contains variables (both dice-roll (enhanced numerics) and strings) as well, conditionals, branching, subroutines with parameters, and a set of built-in functions to simplify working with Roll20 information.<br />
{{script overview<br />
|name=ScriptCards<br />
|author={{user profile|2365448|Kurt J.}}<br />
|code=<br />
|version=1.4.0e<br />
|lastmodified=2021-09-24}}<br />
ScriptCards is not game-system specific, and can be used with any system/sheet. Near the end of this Wiki there is a section set aside for libraries that can implement system-specific tasks, with the hope that enthusiasts playing particular systems will create and share utility functions that can be utilized by the wider community.<br />
<br />
The default display style for ScriptCards output is similar to the format used to document player and NPC abilities in Dungeons and Dragons 4th Edition, but does not have any system ties to D&D4E.<br />
<br />
Current OneClick Version : 1.4.0e<br />
<br />
Current Development Version : 1.4.4<br />
<br />
'''''<big>Critically Important: ScriptCards does not use/parse inline rolls. ScriptCards includes its own built-in dice roll parser to allow for the use of variables inside dice rolls. As of version 1.2.3, ScriptCards will now take inline rolls and substitute the total result value in statement strings, meaning that you can utilize inline rolls but ScriptCards will only see the result of the roll, and not parse the roll components itself.</big>'''''<br />
<br />
* {{fpl|9752053/ ScriptCards thread}}<br />
** {{fpl|10000297/ Scritpcard API Working and Sharing}}<br />
* https://github.com/kjaegers/ScriptCards/tree/main/ScriptCards_API - GitHub repository for source before the one-click version is updated.<br />
* {{yt.be|hyR7Jnq4mQM ScriptCards Intro}} 45min, Jan 2021<br />
* {{yt.be|u50xvNzS9Zk ScriptCards Magic Missile Deep Dive}} 39min, Feb 2021<br />
<br />
<br />
__TOC__<br />
=== Is ScriptCards Related to [[PowerCards]]? ===<br />
<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
Check the '''[[#What to Know if you are Coming from PowerCards|What to Know if you are Coming from PowerCards]]'''-section for a comparison table between the two scripts.<br />
<br />
== What is a ScriptCard Script ==<br />
<br />
A ScriptCard Script is text written into the chat window (either typed directly, pasted, or run via a macro) that will produce a card of information in the [[text Chat|chat window]]. A ScriptCard Script is composed of an [[API]] command: <code><nowiki>!scriptcard {{ }}</nowiki></code> enclosing any number of lines that determine the output that will be added to the card. At it simplest, the following macro:<br />
<br />
<pre>!scriptcard {{ }}</pre><br />
<br />
Will produce just a title card that displays “ScriptCards” as the name:<br />
<br />
[[File:Scriptcard blank.png]]<br />
<br />
Of course, this is just the simplest type of macro and isn’t very useful. In order to produce useful output, we need to include lines between the <code><nowiki>{{</nowiki></code> and <code><nowiki>}}</nowiki></code> that direct the API script as to what it should do.<br />
<br />
== Structure of a ScriptCard Line ==<br />
<br />
All ScriptCard lines begin with two dashes, followed by an ''statement identifier character'' that lets ScriptCards what type of line it is. There are several of these, and they are detailed in the next section. After the line type identifier, a Tag name 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.<br />
<br />
Following the Tag is a vertical bar, and then the content of the line itself. Again, each type of line might interpret this content differently.<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Identifier !! Statement Type !! Tag !! Content !! Notes<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--/</nowiki> || Comment || unused || unused || The <code>--/</code> 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--#</nowiki> || 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").<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--+</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--=</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--&</nowiki> || Assign String 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. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--@</nowiki> || 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 (i.e., [[TokenMod|!token-mod]], or [[ChatSetAttr|!setattr]], etc.)<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--:</nowiki> || 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<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--^</nowiki> || Branch To || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--></nowiki> || Call Procedure || 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<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--<</nowiki> || 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.<br />
|- <br />
| style="white-space:nowrap" | <nowiki>--?</nowiki> || Conditional Branch || Condition to be evaluated || True Branch Label<nowiki>|</nowiki>False Branch Label || The condition will be evaluated and execution will jump to one of the two indicated branches (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 included a semicolon separated list of parameters. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--s</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--l</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--v</nowiki> || 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+'''''<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--e</nowiki> || Echo to Chat || Name to send chat command as || Chat message to send || Variable substitution takes place on the tag and content.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--R</nowiki> || Retrieve Repeating Section Row information || "find", "first", or "next" || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--~</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--c</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--i</nowiki> || Information Request || User Prompt;Button Caption || InfoType;VariableName;ParameterText || See full documentation below.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--d</nowiki> || 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. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--%</nowiki> || 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. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--*</nowiki> || 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.<br />
|}<br />
<br />
== ScriptCard Statement Type Details ==<br />
The sections below detail the individual statement types supported by ScriptCards<br />
<br />
=== Comment (--/) ===<br />
<br />
A --/ statement is ignored by the ScriptCards parser. You can use this type of statement to add comments and informational text to your script. <br />
<br />
Example:<br />
<pre><br />
!script {{<br />
--/|Script Name : Fireball<br />
--/|Purpose : Allow the player to cast a fireball and blow stuff up!<br />
.<br />
.<br />
.<br />
}}<br />
</pre><br />
<br />
Using this style will sometimes work, but is not recommended.<br />
<pre><br />
!script {{<br />
--/|When you have a very<br />
long comment, then<br />
you sometimes have<br />
to put it in multiple<br />
lines.<br />
.<br />
.<br />
.<br />
}}<br />
</pre><br />
Because it can lead to unwanted text appearing on your output card.<br />
<br />
=== Set Parameter (--#) ===<br />
<br />
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.<br />
<br />
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.<br />
<br />
'''''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.'''''<br />
<br />
Examples:<br />
<pre><br />
--#title|Magic Missile<br />
--#leftsub|Level 1 Spell<br />
--#rightsub|Force Damage<br />
</pre><br />
<br />
The three examples above set the “title”, “leftsub”, and “rightsub” values for the card to the content value for the line. <br />
<br />
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.<br />
Settings Lines do not produce output lines on the card.<br />
<br />
The following settings are available (note that parameter names are ''not'' case sensitive):<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Name !! Effect/Use !! Default Value !! Type<br />
|-<br />
| 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<br />
|-<br />
| allowplaintextinrolls || If set to a non-zero value, plain character text in rolls will be copied to the roll text || 0 || Per-Line<br />
|-<br />
| bodyFontFace || Name of the font used in the card rows || Helvetica || Global<br />
|-<br />
| bodyFontSize || Size of the text in the card rows || 14px || Global<br />
|-<br />
| bodybackgroundimage || Specify an image (content for a CSS background-image tag) for the body area || none || Global<br />
|-<br />
| buttonBackground || Background color for buttons created with [button][/button] || #1C6EA4 || Per-Line<br />
|-<br />
| buttonBorderColor || Border (outline) color for buttons created with [button][/button] || #999999 || Per-Line<br />
|-<br />
| buttonFontFace || Font Family specifier for captions on buttons created with [button][/button] || Tahoma || Per-Line<br />
|-<br />
| buttonFontSize|| Text size for captions on buttons created with [button][/button] || x-small || Per-Line<br />
|-<br />
| buttonTextColor|| Text color of labels on buttons created with [button][/button] || #FFFFFF || Per-Line<br />
|-<br />
| 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<br />
|-<br />
| deferralcharacter || Changes the meta script deferral sequence to the specified value || ^ || Per-Line<br />
|-<br />
| diceFontColor|| Color of the dice created with the [d4] [d6], etc. formatting markers || #1C6EA4 || Per-Line<br />
|-<br />
| dicefontsize || Size of the dice created with the [d4] [d6], etc. formatting markers || 3.0em || Per-Line<br />
|-<br />
| 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<br />
|-<br />
| disablerollprocessing || If set to a non-zero value, --= lines will not process dice rolls strings || 0 || Per-Line<br />
|-<br />
| emoteBackground || Background color of the emote area || #f5f5ba || Global<br />
|-<br />
| emoteFont || Name of the font used in emote area (above the title of the output card) || Georgia || Global<br />
|-<br />
| emoteFontColor || Color of the font in the emote area || None (Empty) || Global<br />
|-<br />
| emoteFontSize || Size of the font used in the emote area || 14px || Global<br />
|-<br />
| emoteFontWeight || Font weight for the font in the emote area || bold|| Global<br />
|-<br />
| emoteState || If set to anything other than "visible", the emote portion of the card will not be displayed || visible || Global<br />
|-<br />
| emoteText || Text to display in the emote portion of the card || None (Empty) || Global<br />
|-<br />
| emotefont || Name of the font used in the emote text area || font-family: Georgia, serif; font-weight: bold; || Global<br />
|-<br />
| evenRowBackground || Hex code for the background color for even rows || #eeeeee || Per-Line<br />
|-<br />
| evenRowFontColor || Hex code for the text color for even rows || #000000 || Per-Line<br />
|-<br />
| evenrowbackgroundimage || Specify an image (content for a CSS background-image tag) for the even card rows || none || Per-Line<br />
|-<br />
| executionlimit || Maximum number of script lines the interpreter will try to execute. This prevents "infinite loop" sandbox crashes || 40000 || Global<br />
|-<br />
| hideCard || If set to any non-default value, the entire card output will be suppressed || 0 || Global<br />
|-<br />
| 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<br />
|-<br />
| 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<br />
|-<br />
| lineheight || Vertical size of each line on the output card || normal || Per-Line<br />
|-<br />
| nominmaxhighlight || If set to anything other than "0", rolls will not display crit/fumble/mixed highlight colors. || 0 || Per-Line<br />
|-<br />
| norollhighlight || If set to anything other than "0", rolls will not be formatted (plain numbers) but will still get a tooltip with details ('''''v1.3.6b+''''') || 0 || Per-Line<br />
|-<br />
| oddRowBackground || Hex code for the background color for even rows || #d0e4f5 || Per-Line <br />
|-<br />
| oddRowFontColor || Hex code for the text color for odd rows || #000000 || Per-Line<br />
|-<br />
| oddrowbackgroundimage || Specify an image (content for a CSS background-image tag) for the odd crd rows || none || Per-Line<br />
|-<br />
| reentrant || Used to name a script for rentrant button use || 0 || Global<br />
|-<br />
| 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)0 || Global<br />
|-<br />
| rollhilightlineheight || Determines the height of the hilight box placed around roll results ('''''1.4.2+''''') || 1.0em || Per-Line<br />
|-<br />
| roundUp || If set to a non-default value, integer division will round up instead of down || 0 || Per-Line<br />
|-<br />
| showfromfornonwhispers || If set to a non-zero value, will include the sender on cards that aren't whispered || 0 || Global<br />
|-<br />
| 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<br />
|-<br />
| subtitleFontColor || Color of the text in the subtitle areas || #FFFFFF || Global<br />
|-<br />
| subtitleFontFace || Name of the font used on the subtitle sections || Tahoma || Global<br />
|-<br />
| subtitleFontSize || Size of the subtitle font || 13px || Global<br />
|-<br />
| subtitleSeperator || The character(s) that will be placed between leftsub and rightsub || <nowiki>&#x2666</nowiki>; || Global<br />
|-<br />
| tableBorderRadius || CSS specifier for how rounded the borders of the output card are. Use "0px;" for square borders || 6px; || Global<br />
|-<br />
| tableShadow || CSS specifier for the drop shadow under the output card || 5px 3px 3px 0px #aaa; || Global<br />
|-<br />
| tablebgcolor || Background color of the whole card. '''''Normally not visible''''' || #EEEEEE || Global<br />
|-<br />
| tableborder || Color of the border that surrounds the whole card || 2px solid #000000; || Global<br />
|-<br />
| 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<br />
|-<br />
| timezone || IANA Specifier for the local time zone, used in system/date functions || merica/New_York || Per-Line<br />
|-<br />
| title || Text displayed in the title area of the card || ScriptCards || Global<br />
|-<br />
| titleCardBackground || A hex color code representing the background color of the title area. || #1c6ea4 || Global<br />
|-<br />
| titleFontColor || Color of the text on the card title || #FFFFFF || Global<br />
|-<br />
| titleFontFace || Name of the font used on the title area || Contrail One || Global<br />
|-<br />
| titleFontLineHeight || Line spacing on the title area || 1.2em || Global<br />
|-<br />
| titleFontSize || Size of the title font || 1.2em || Global<br />
|-<br />
| titlecardbackgroundimage || Specify an image (content for a CSS background-image tag) for the title card area || none || Global<br />
|-<br />
| titlecardbottomborder || Border CSS specifier for the bottom of the title card area || 2px solid #444444; || Global<br />
|-<br />
| titlecardgradient || If set to non-zero value, will place a vertical gradient on the title card area || 0 || Global<br />
|-<br />
| usehollowdice || If set to a non-zero value, the hollow/outline versions of the dice fonts will be used || 0 || Per-Line<br />
|-<br />
| whisper|| Comma separated list of who to whisper the output to. Use "gm" for [[GM|GMs]] and "self" for the sender || none || Global|}<br />
|}<br />
<br />
''Setting Lines do not produce output lines on the card''<br />
<br />
=== Direct Output (--+) ===<br />
<br />
A direct output line display 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.<br />
<br />
Examples of Direct Output lines:<br />
<pre><br />
--+Hello|World<br />
--+Attack|The monster rolls [$Attack] to hit!<br />
--+Damage|@{target|token_name} is hit for [$Damage] [#3333AA][b]frost[/b][/#] damage.<br />
</pre><br />
<br />
Direct Output lines support inline formatting, roll variable replacement, character attribute references, and procedure variables.<br />
<br />
=== GM Output (--*) ===<br />
<br />
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. <br />
<br />
Example:<br />
<pre><br />
--+PlayerLine|This line is shown on the public card<br />
--*GMLine|This line will only be shown to GMs, on a separate card.<br />
</pre><br />
<br />
=== Roll Variable Assignment (--=) ===<br />
<br />
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.<br />
<br />
'''''All components of a roll equation should be separated with spaces.'''''<br />
<br />
Examples:<br />
<pre><br />
--=MissileDamage|1d4 + 1<br />
--=Attack|1d20 + @{selected|strength_mod} [STR] + @{selected|pb} [PROF]<br />
</pre><br />
<br />
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. Text enclosed in square brackets ([]) is considered "flavor text" and will be added to the result text but does not impact the roll result.<br />
<br />
The following dice formats are supported:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Format Pattern !! Example !! Description<br />
|-<br />
| XdY || 3d8 || Simple format. Roll a Y-sided die X times<br />
|-<br />
| XdYkhZ || 2d20kh1 || Roll Y-sided die X times and keep the highest Z number of dice<br />
|-<br />
| XdYklZ || 4d6kl3 || Roll Y-sided die X times and keep the lowest Z number of dice <br />
|-<br />
| XdY>Z || 5d6>3 || Roll Y-sided die X times and count a 1 for each roll greater than Z <br />
|-<br />
| XdY<Z || 5d6<3 || Roll Y-sided die X times and count a 1 for each roll less than Z <br />
|}<br />
<br />
'''''Note: The dice formulae below are supported in the development version of ScriptCards and will be merged with the table above when activated on OneClick'''''<br />
::{| class="wikitable"<br />
|-<br />
! Format Pattern !! Example !! Description<br />
|-<br />
| 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<br />
|-<br />
| 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<br />
|-<br />
| 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)<br />
|-<br />
| 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<br />
|}<br />
<br />
The following operators are supported in a roll equation:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Operator !! Operation<br />
|-<br />
| + || Addition <br />
|-<br />
| - || Subtraction <br />
|-<br />
| * || Multiplication <br />
|-<br />
| / || Division <br />
|-<br />
| \ || Integer Division (Rounds down) <br />
|-<br />
| % || Modulo (Remainder of Divison)<br />
|}<br />
<br />
Roll Variables can be accessed at any time after they have been created by using the [$VariableName] format, with the following optional modifiers:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Modifier !! Meaning<br />
|-<br />
| No modifier || In a Direct Output Line (<nowiki>--+</nowiki>) 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<br />
|-<br />
| .Total || The end result of the roll equation as an unformatted number <br />
|-<br />
| .Base || The cumulative result of any dice rolled in the Roll Text (Numeric modifiers are not included) <br />
|-<br />
| .Ones || The number of dice in the roll that came up as 1s <br />
|-<br />
| .Aces || The number of dice in the roll that came up as the maximum number on the die <br />
|-<br />
| .Odds || The number of dice in the roll that came up with an odd number <br />
|-<br />
| .Evens || The number of dice in the roll that came up with an even number <br />
|-<br />
| .RollText || The raw text of the roll that was use to generate the results <br />
|-<br />
| .Text || A text representation of the results of the roll, including the numbers rolled for each die <br />
|-<br />
| .tableEntryText || The text portion of the result of a table roll<br />
|-<br />
| .tableEntryImgURL || The image source portion of the result of a table roll<br />
|-<br />
| .tableEntryValue || Numeric value of tableEntryText (via parseInt). If a non-numeric value, will be 0<br />
|-<br />
| .Raw || The total numeric result without any formatting, even if placed somewhere formatting would normally be done. <br />
|}<br />
<br />
Examples:<br />
<pre><br />
--+Total Damage|[$MissileDamage.Total] (roll was 1d4+1)<br />
--+Base Damage|[$MissileDamage.Base] (without the +1)<br />
--=Attack|1d20 + @{selected|strength_mod} [STR] + @{selected|pb} [PROF] + [$BlessBonus] [Bless]<br />
</pre><br />
<br />
In this case, 1d4 will be rolled and stored in “BlessBonus”, which can then be used in the Attack line.<br />
<br />
'''''Mathematical Functions in Roll Expressions '''''<br />
<br />
The ScriptCards roll parser works from left to right, always maintaining a current value and applying whatever comes next to the total. The following in-line functions to the roll parser. These are:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Expression !! Meaning<br />
|-<br />
| {ABS} || Absolute Value<br />
|-<br />
| {CEIL} || Ceiling value (round up to the next whole number)<br />
|-<br />
| {FLOOR} || Floor value (round down to the next whole number)<br />
|-<br />
| {ROUND} || Round value (round up if the decimal portion is greater than 0.5, otherwise round down)<br />
|-<br />
| {NEGATE} || Multiply the value by negative one.<br />
|-<br />
| {SQRT} || Take the square root of the running value. ('''''1.4.1+''''')<br />
|-<br />
| {SQUARE} || Square the running value. ('''''1.4.2+''''')<br />
|-<br />
| {CUBEROOT} || Take the cube root of the running value. ('''''1.4.2+''''')<br />
|-<br />
| {CUBE} || Cube the running value. ('''''1.4.2+''''')<br />
|-<br />
| {SIN} || Return the SIN of running value. ('''''1.4.2+''''')<br />
|-<br />
| {COS} || Return the COS of running value. ('''''1.4.2+''''')<br />
|-<br />
| {TAN} || Return the TAN of running value. ('''''1.4.2+''''')<br />
|-<br />
| {ASIN} || Return the ASIN of running value. ('''''1.4.2+''''')<br />
|-<br />
| {ACOS} || Return the ACOS of running value. ('''''1.4.2+''''')<br />
|-<br />
| {ATAN} || Return the ATAN of running value. ('''''1.4.2+''''')<br />
|}<br />
<br />
<br />
'''''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 <nowiki>[[ ]]</nowiki> 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.<br />
<br />
'''''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.<br />
<br />
'''Rolling on Rollable Tables'''<br />
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.<br />
<br />
''Roll Variable Lines do not produce output lines on the card.''<br />
<br />
=== String Variable Assignment (--&) ===<br />
<br />
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:<br />
<br />
<pre><br />
--&MyText|Hello<br />
</pre><br />
<br />
Here, we assign the text "Hello" to the string variable named MyText. You can also append text to a string variable by prefixing the content with a + sign:<br />
<br />
<pre><br />
--&MyText|+ World<br />
</pre><br />
<br />
If run after the statement above, MyText will now contain "Hello World".<br />
<br />
String variables can be referenced using the syntax [&variablename]<br />
<br />
=== Call API (--@) ===<br />
<br />
ScriptCards can use a Call API instruction to execute other API commands. The Tag contains the API 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 API command is executed.<br />
<br />
Examples:<br />
<pre><br />
--@eh|list<br />
--@alter|_target|@{target|token_id} _bar|3 _amount|-[$Damage]<br />
</pre><br />
<br />
In the first example above, the command <code>!eh list</code> will be executed, calling [[EncounterHelper]]. In the second, {{fpl|1216260/ AlterBars}} is called to modify a token's Bar 3 value.<br />
<br />
'''''Note:''''' When ScriptCards (or any API script) runs other API 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).<br />
<br />
See [[API:Script Index]] for more options.<br />
<br />
=== Branch Label (--:) ===<br />
<br />
A branch label defines a line in your code that can be reached by one of the branching instructions (<nowiki>--^</nowiki>, <nowiki>--></nowiki>, or <nowiki>--?</nowiki>). The Tag serves as the label name, and must be unique on the card.<br />
<br />
The vertical bar (|) separator must be present, but the content portion of the line is unused and can be treated as a comment.<br />
<br />
Examples:<br />
<pre><br />
--:MyLoop|<br />
--:CriticalHit|Will jump here if we roll a critical hit!<br />
</pre><br />
<br />
''A Branch Label line does not produce an output line on the card.''<br />
<br />
=== Branch (--^) === <br />
<br />
A Branch line 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.<br />
<br />
Examples:<br />
<pre><br />
--^MyLoop|Jumps to MyLoop<br />
--^SkipCrit|We didn't crit, so skip the Crit code<br />
</pre><br />
<br />
''A Branch line does not produce an output line on the card.''<br />
<br />
=== Call Procedure (-->) ===<br />
<br />
Similar to a branch, a Call Procedure (sometimes knows 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 (<nowiki>--<</nowiki>) 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 (;).<br />
<br />
Examples:<br />
<pre><br />
-->FixFormat|#3333FF;#999999<br />
</pre><br />
<br />
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%].<br />
<br />
=== Return (--<) ===<br />
<br />
A return instruction marks the end of a Gosub procedure. 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.<br />
<br />
Examples:<br />
<pre><br />
--<|<br />
--<|End of MySub<br />
</pre><br />
<br />
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.<br />
<br />
=== Conditional Statement (--?) ===<br />
<br />
A conditional statement contains some equation in the Tag that will be evaluated. '''''If any part of the comparison can/does contain a space, it needs to be surrounded by double quotes'''''<br />
<br />
Based on the true/false result of the evaluation, one of two execution paths will be taken. These execution paths are detailed in the content section of the statement. The "if true" path is specified first (directly after the vertical bar), and the "if false" path is specified after it, also separated by a vertical bar.<br />
<br />
Example:<br />
<pre><br />
--?[$AttackRoll.Total] -ge [$TargetAC]|Hit|Miss<br />
</pre><br />
<br />
'''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.'''<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Branch Format !! Meaning<br />
|-<br />
| Label || If just a label is specified, execution will branch to that label when the comparison is matched.<br />
|-<br />
| >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 <br />
|-<br />
| =VariableName || The roll variable "VariableName" will be assigned the value following a semicolon (ex: --?1 -eq 1|=Roll;1d20)<br />
|-<br />
| &VariableName || The string variable "VariableName" will be assigned the value following a semicolon (ex: --?1 -eq 1|&Result;Hit|&Result;Miss)<br />
|-<br />
| % or %! || The current for...next loop will perform the "next" action (%) or will break out (%!) <br />
|-<br />
| [ || Code block (see below)<br />
|}<br />
<br />
Examples:<br />
<pre><br />
--?[$AttackRoll.Base] -eq 20|CriticalHit<br />
--?[$AttackRoll.Base] -eq 1|>Fumble;@{selected|dexterity_mod}<br />
--?"@{target|npc_type}" -inc "undead"|&MonsterType;Undead|&MonsterType;Not Undead<br />
--?[$Attack.Total] >= [$ArmorClass]|>Hit|>Miss<br />
</pre><br />
<br />
In the first example, if the Base value of AttackRoll is a 20 (natural 20 on the die) execution will branch to the CriticalHit label.<br />
<br />
In the second example, 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%].<br />
<br />
The third example looks for the word "undead" in the npc_type attribute of the targeted character. If it exists in the text, the MonsterType string variable will be set to "Undead", otherwise it will be set to "Not Undead". <br />
<br />
The final example would call 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.<br />
<br />
''Text that does/may contain a space should be enclosed in double quotes.''<br />
<br />
The following comparison operators are available:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Comparator !! Meaning<br />
|-<br />
| -eq || Equal To <br />
|-<br />
| -eqi || Case insensitive Equal To <br />
|-<br />
| -ne || Not Equal To <br />
|-<br />
| -nei || Case insensitive Not Equal To <br />
|-<br />
| -gt || Greater Than <br />
|-<br />
| -ge || Greater Than or Equal To <br />
|-<br />
| -lt || Less Than <br />
|-<br />
| -le || Less Than or Equal To <br />
|-<br />
| -inc || Includes (text strings). <br />
|-<br />
| -ninc || Does Not Include (text strings). <br />
|}<br />
<br />
Multi-part conditionals are supported with -and and -or as separators. For example:<br />
<br />
<pre><br />
--?[$Attack.Total] -ge @{target|npc_ac} -and [$Attack.Base] -ne 20|HitButNotCrit<br />
</pre><br />
<br />
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):<br />
<br />
true AND false OR true<br />
<br />
Will be evaluated as true. The first two (true and false) will be false, but then false OR true will be true.<br />
<br />
Conversely:<br />
<br />
true or false and false<br />
<br />
Will be false, because the first true and false will evaluate to true, and then true and false will be false.<br />
<br />
'''CODE BLOCKS'''<br />
<br />
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.<br />
<br />
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:<br />
<br />
<pre><br />
!script {{<br />
--=Roll|1d2<br />
--+Roll|[$Roll]<br />
--?[$Roll.Total] -eq 2|[<br />
--&Value|Yep!<br />
--+|We are inside the TRUE portion of the block<br />
--]|[<br />
--&Value|Nope<br />
--+|We are inside the FALSE portion of the block<br />
--]|<br />
--+After|the blocks!<br />
--+Value|[&Value]<br />
}}<br />
</pre><br />
<br />
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 --]|. <br />
<br />
At this time, blocks cannot be nested, and can only be created as part of a conditional (--[ is not a valid statement type)<br />
<br />
''A conditional statement does not produce a line of output on the card.''<br />
<br />
=== Case Statement (--c) ===<br />
<br />
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 (:). Each match condition includes a branch label that will be used if the test value matches the item. 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:<br />
<br />
<pre><br />
!script {{<br />
--#title|Case Statement Testing<br />
--=Roll|1d4<br />
--C[$Roll.Total]|1:>One;[$Roll]|2:>Two;[$Roll]|3:>Three;[$Roll]|4:>Four;[$Roll]<br />
--X|<br />
<br />
--:One| --+Value|was One ([%1%]) --<|<br />
--:Two| --+Value|was Two ([%1%]) --<|<br />
--:Three| --+Value|was Three ([%1%]) --<|<br />
--:Four| --+Value|was Four ([%1%]) --<|<br />
}}<br />
</pre><br />
<br />
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 variable as a parameter.<br />
<br />
=== Save and Load (--s and --l) ===<br />
<br />
This statement pair is used to either store (--s) or load (--l) data from persistent storage. Items stored in persistent storage remain between card rolls and between Roll20 sessions. There are two types of data that can be stored: settings and roll variables. <br />
<br />
Examples:<br />
<br />
<pre><br />
--Ssettings|GreenStyle<br />
--Srollvariables|FirstCardVars<br />
</pre><br />
<br />
In this case, the tag for the statement determines what type of item is being saved (settings or rollvariables). When saving settings, all non-default settings are written to the named setting storage value. When Roll Variables are saved, all variables that currently exist will be saved to the named storage value.<br />
<br />
Loading stored items simply requires the same command with the --l statement type:<br />
<br />
<pre><br />
--Lsettings|GreenStyle<br />
--Lrollvariables|FirstCardVars<br />
</pre><br />
<br />
When loading settings, all stored settings will be applied to the current card settings. You can override settings by changing them after the load.<br />
<br />
When loading roll variables, the saved variables will be added to (or overwrite if they have the same name) any variables on the current card. This means it is safe to create roll variables before the load statement.<br />
<br />
'''Practical Uses'''<br />
The major intended use of persistent storage is for storing card formats for use in later scripts. For example, the following script:<br />
<br />
<pre><br />
!scriptcard {{<br />
--#titlecardbackground|#22CC22<br />
--#oddrowbackground|#cceecc<br />
--#evenrowbackground|#99ee99<br />
--Ssettings|@{selected|token_name}<br />
}}<br />
</pre><br />
<br />
Would save the titlecardbackground, oddrowbackground, and evenrowbackground settings to a saved list named after the selected token's name. When creating cards for that token to run later, you could include the line:<br />
<br />
<pre><br />
--Lsettings|@{selected|token_name}<br />
</pre><br />
<br />
To load all of the settings at once. By creating these setting sets for each character, you can specify a different color scheme for each character that can then be used in cards with a single formatting line.<br />
<br />
There is a supplemental ! command added to support saved settings:<br />
<br />
<pre><br />
!sc-liststoredsettings<br />
</pre><br />
<br />
Will produce a list of all stored setting names, with buttons to list the setting values stored in each group and a button to delete groups as needed.<br />
<br />
=== Visual Effects (--v) ===<br />
<br />
The --v statement can be used to create visual effects on the tabletop. The tag portion of the statement can be either "token" or "betweentokens". The content portion of the statement contains the required parameters for the effect generation, separated by spaces. If the effect is "none", no effect will be played. If any other value that doesn't match a Roll20 effect name will result in a burst-fire effect.<br />
<br />
For "token" effects, the parameters are the token id for the token the effect happens on, followed by the effect specifier.<br />
<br />
Example:<br />
<pre><br />
--vtoken|@{selected|token_id} burst-fire<br />
</pre><br />
<br />
For "betweentoken" effects, the parameters are the source token id, the target token id, and the effect specifier.<br />
<br />
Example:<br />
<pre><br />
--vbetweentokens|@{selected|token_id} @{target|token_id} beam-magic<br />
</pre><br />
<br />
'''''Version 1.2.8+'''''<br />
<br />
An additional effect specifier, "point" is available in 1.2.8+. This specifier allows you to create a visual effect at a designated X/Y pixel coordinate. Future updates will add custom-vfx support to this option. The parameters are the X and Y coordinates and the effect descriptor. As of version 1.2.9, you can also use custom effect specifiers with Point effects:<br />
<br />
<pre><br />
--vpoint|150 200 burst-fire<br />
</pre><br />
<br />
=== Echo to Chat (--e) ===<br />
<br />
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.<br />
<br />
Example:<br />
<pre><br />
--eThe Ghost|/em hovers around @{selected|character_name}... BOO!<br />
</pre><br />
<br />
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).<br />
<br />
'''''Whispering'''''<br />
<br />
You can use the echo statement to send a whisper, but there's a trick to it. If you execute this code here:<br />
<br />
<pre><br />
--eThe Ghost|/w ExamplePlayerName Boo.<br />
</pre><br />
<br />
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.<br />
<br />
So, in conclusion, it's best to use something like this when you're sending a whisper:<br />
<br />
<pre><br />
!script {{<br />
--#hidecard|1<br />
--&sender|The Ghost<br />
--&receiver|ExamplePlayerName<br />
--&message|Boo.<br />
--e[&sender]|/w [&receiver] [&message]<br />
--eScriptCards|/w gm **Whispered from [&sender] to [&receiver]:** [&message] <br />
}}<br />
</pre><br />
<br />
This will ensure that the message appears in your chat feed as well.<br />
<br />
=== Repeating Section Access (--R) ===<br />
<br />
ScriptCards (as of v0.0.13) supports accessing repeating section rows on a character sheet with the --R statement type. <br />
<br />
There are three basic commands you can use with --R, and they are specified by the tag used:<br />
<br />
<pre><br />
--Rfind|characterid;EntryName;SectionPrefix;SearchField<br />
</pre><br />
<br />
This is the most direct way to access a repeating section row. Supplying the character ID, followed by what you are looking for (Greatsword, for example), followed by the character sheet's section prefix (repeating_attack), followed by the field to check what you are searching for (atkname) will load the matching section (if found) into the script parsers memory. For example:<br />
<br />
<pre><br />
--Rfind|@{selected|character_id};Greatsword;repeating_attack;atkname<br />
</pre><br />
<br />
Will look at the character's "repeating_attack" section for an entry with an atkname value equal to "Greatsword". Similarly:<br />
<br />
<pre><br />
--Rfind|@{selected|character_id};Bite;repeating_npcaction;name<br />
</pre><br />
<br />
Will look for a "Bite" action on an NPC's action list.<br />
<br />
<pre><br />
--Rfirst|characterid;section prefix<br />
</pre><br />
<br />
This form of the --R command will look at all of the entries in the specified repeating section and load the first one into memory:<br />
<br />
<pre><br />
--Rfirst|@{selected|character_id};repeating_attack<br />
</pre><br />
<br />
Would load the character's first "repeating_attack" row into memory.<br />
<br />
<pre><br />
--Rnext|<br />
</pre><br />
<br />
No parameters are required for --Rnext, which loads the next entry in the list that was obtained with "first" into memory.<br />
<br />
However a row is obtained, it will be parsed to replace any attribute references (ie, @{level}) with the corresponding character attribute.<br />
<br />
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".<br />
<br />
You can reference repeating attribute data using the syntax [*R:attributename] syntax (similar to referencing standard character attributes).<br />
<br />
Here are some examples:<br />
<br />
Display the details of the "Greatsword" PC attack:<br />
<br />
<pre><br />
!script {{<br />
--Rfind|@{selected|character_id};Greatsword;repeating_attack;atkname<br />
--+Attack Name|[*R:atkname]<br />
--+Base Damage|[*R:dmgbase]<br />
}}<br />
</pre><br />
<br />
[[File:Scriptcards repeating greatsword.png|Repeating Greatsword Attack]]<br />
<br />
List all of the actions an NPC can take (just actions, not legendary, etc.)<br />
<br />
<pre><br />
!script {{<br />
--#title|NPC Actions<br />
--#leftsub|@{selected|token_name}<br />
--Rfirst|@{selected|character_id};repeating_npcaction<br />
--:DisplayLoop|<br />
--?"[*R:name]" -eq NoRepeatingAttributeLoaded|Done<br />
--+Action:|[*R:name] [*R:attack_damage] [*R:attack_damagetype]<br />
--?"[*R:attack_damage2]" -eq ""|NoSecondaryDamage<br />
--+ |[*R:attack_damage2] [*R:attack_damagetype2]<br />
--:NoSecondaryDamage|<br />
--Rnext|<br />
-->DisplayLoop| <br />
--:Done|<br />
}}<br />
</pre><br />
<br />
[[File:Scriptcards repeating npcactions.png]]<br />
<br />
In the script above, we get the "first" repeating_npcaction and display information about it. We then execute "next" and repeat until we run into "NoRepeatingAttributeLoaded".<br />
<br />
'''''Special debugging command: dump'''''<br />
<pre><br />
--Rdump|<br />
</pre><br />
<br />
The "dump" command will list all of the attributes ScriptCards knows about for the currently loaded repeating row to the API Console Log.<br />
<br />
=== Assign Variable to Built-In Function (--~) ===<br />
<br />
ScriptCards has the ability to run a function built into the API script and return the results to a variable. Some functions return roll variables, while others return strings. See the function table below for details. The format is:<br />
<br />
--~VariableName|function;param1;param2;param3;...<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Function Name !! Parameters !! Description<br />
|-<br />
| distance || token_A_ID;token_B_ID || Calculate the Chebyshev distance in grid units between two tokens. This is the measurement scheme D&D 4E/5E use for diagonal distance measurement<br />
|-<br />
| euclideandistance || token_A_ID;token_B_ID || Calculate the Euclidean distance between two tokens. This is essentially the Pythagorean theorem in action. Returns the result in grid units.<br />
|-<br />
| euclideanpixel || token_A_ID;token_B_ID || Calculate the Euclidean distance between two tokens and returns the result is pixels instead of grid units. <br />
|-<br />
| euclideanlong || token_A_ID;token_B_ID || 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 is calculated instead of before. More accurate over long distances. <br />
|-<br />
| manhattandistance || token_A_ID;token_B_ID || Also called "taxicabdistance" (which is an acceptable function name), this measures to how-many-over, how-many-up/down distance, disallowing diagonal movement.<br />
|-<br />
| getselected || none || 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 the first selected token, VariableName2 the second, etc.<br />
|}<br />
<br />
'''''Functions with Sub Functions'''''<br />
<br />
Most ScriptCards functions are grouped into set as sub functions. The table below lists the major functions and their sub functions.<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Function Name !! Sub Function !! Parameters !! Return Type !! Description<br />
|-<br />
| array || define || arrayname;value1;value2;... || none || Creates an array called "arrayname" and adds value1, value2, etc. to the array<br />
|-<br />
| array || sort || arrayname || none || Sorts the specified array in place in ascending order<br />
|-<br />
| array || add || arrayname;value1;value2;... || none || Adds value1, value2, ... to the existing array "arrayname"<br />
|-<br />
| array || remove || arrayname;value1;value2;... || none || Removes value1, value2, ... from the existing array "arrayname". Resets the array index to 0.<br />
|-<br />
| array || replace || arrayname;currentvalue;newvalue || none || Replaces all occurrences of "currentvalue" in "arayname" with "newvalue"<br />
|-<br />
| array || setatindex || arrayname;index;newvalue || none || Replaces the array item at index "index" with "newvalue"<br />
|-<br />
| array || getindex || arrayname || stringVariable || Retrieves the current index in "arrayname" and stores it in the supplied string variable<br />
|-<br />
| array || setindex || arrayname;newindex || none || Sets the current index in array "arrayname" to "newindex"<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| array || removeat || arrayname;indexposition || none || Removes the item at index "indexposition" from "arrayname". Resets the current array index to 0.<br />
|-<br />
| array || indexof || arrayname;searchvalue || stringVariable || Searches the array "arrayname" for and item with the value of "searchvalue" and, if found, returns the index of the first matching value or "ArrayError" if not found<br />
|-<br />
| array || getlength || arrayname || stringVariable || Returns the number of items in array "arrayname"<br />
|-<br />
| array || pagetokens || arrayname;tokenid;(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. 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.)<br />
|-<br />
| 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.<br />
|-<br />
| array || stringify || arrayname || stringVariable || Returns all of the items in "arrayname" as a string separated by semicolons (;)<br />
|-<br />
| array || fromstring || arrayname || delimiter;string || Creates an array from "string", splitting "string" on "delimiter" to separate the items<br />
|-<br />
| array || statusmarkers|| arrayname;tokenid || none|| Creates an array (arrayname) of the active statusmarkers (sometimes called Token Markers) for the specified tokenid<br />
|-<br />
| math || angle || math;angle;tokenid;tokenid|| rollVariable || Calculates the angle between two tokens and returns the value in degrees<br />
|-<br />
| math || ceil || math;ceil;value || rollVariable || Rounds '''value''' up to the next integer, dropping any decimal portion of the number<br />
|-<br />
| math || clamp || math;clamp;value;lowerBound;upperBound || rollVariable || Returns '''value''', but restricted to the range of '''loweBound''' and '''upperBound'''.<br />
|-<br />
| math || floor || math;floor;value || rollVariable || Rounds '''value''' down, dropping any decimal portion of the number<br />
|-<br />
| math || max || math;max;valueA;valueB || rollVariable || Returns the larger of '''valueA''' vs '''valueB'''<br />
|-<br />
| math || min || math;min;valueA;valueB || rollVariable || Returns the smaller of '''valueA''' vs '''valueB'''<br />
|-<br />
| math || round || math;round;value || rollVariable || Rounds '''value''' to the nearest integer<br />
|-<br />
| string || length || string;length;stringValue || rollVariable || Returns the length of '''stringValue''' in characters<br />
|-<br />
| string || before || string;before;searchText;stringValue || stringVariable || Searches '''stringValue''' for '''searchText''' and returns the portion of '''stringValue''' prior to that text<br />
|-<br />
| string || after || string;after;searchText;stringValue || stringVariable || Searches '''stringValue''' for '''searchText''' and returns the portion of '''stringValue''' after that text<br />
|-<br />
| string || left || string;left;count;stringValue || stringVariable || Returns the leftmost '''count''' characters of '''stringValue'''<br />
|-<br />
| string || right || string;right;count;stringValue || stringVariable || Returns the rightmost '''count''' characters of '''stringValue'''<br />
|-<br />
| string || replace || string;replace;searchText;replaceText;stringValue || stringVariable || Replaces '''searchText''' in '''stringValue''' with '''replaceText''' and returns the resulting string<br />
|-<br />
| string || replaceall || string;replace;searchText;replaceText;stringValue || stringVariable || Replaces all intances of '''searchText''' in '''stringValue''' with '''replaceText''' and returns the resulting string '''''Requires 1.2.9+'''''<br />
|-<br />
| string || trim || string;trim;stringValue || stringVariable || Removes leading and trailing spaces from stringValue and returns the result. <br />
|-<br />
| string || substring || string;substring;start;count;stringValue || stringVariable || Returns '''count''' characters starting at '''start''' from '''stringValue'''<br />
|-<br />
| 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.<br />
|-<br />
| string || tolowercase || string;tolowercase;stringValue || stringVariable || Converts the passed string to lower case and assigns to the passed variable name. <br />
|-<br />
| string || touppercase || string || stringVariable || Converts the passed string to upper case and assigns to the passed variable name. <br />
|-<br />
| 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. <br />
|-<br />
| 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.<br />
|-<br />
| 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'''.<br />
|-<br />
| turnorder || clear || none || none || Clears all entries from the {{Turn Tracker}}/Initiative<br />
|-<br />
| turnorder || addtoken || tokenid;trackervalue || none || Adds the token represented by "tokenid" to the initiative tracker with an initiavie value of "trackervalue"<br />
|-<br />
| turnorder || replacetoken || tokenid;trackervalue || none || Replaces the token represented by "tokenid" in the initiative tracker with an initiavie value of "trackervalue". Will add the token if it doesn't exist in the tracker.<br />
|-<br />
| turnorder || removetoken || tokenid || none || Removes the token represented by "tokenid" from the initiative tracker if it exists<br />
|-<br />
| turnorder || addcustom || textlabel;trackervalue || none || Add a custom text entry to the {{Turn Tracker}}/Initiative named "textlabel" with an initiative value of "trackervalue"<br />
|-<br />
| system || date || getdatetime || stringVariable || Returns the date time in the active timezone (see settings) <br />
|-<br />
| system || date || getdate || stringVariable || Returns the date in the active timezone (see settings) <br />
|-<br />
| system || date || gettime || stringVariable || Returns the time in the active timezone (see settings)<br />
|-<br />
| system || dumpvariables || "rolls", "string", or "array" || none || Dumps all of the defined variables of the indicated type to the console log<br />
|-<br />
| system || findability || system;findability;charactername;abilityname || stringVariable || Returns the object ID of the ability on the indicated character or "AbilityNotFound"<br />
|-<br />
|}<br />
<br />
Examples:<br />
<br />
<pre><br />
--~HowFarAway|distance;@{selected|token_id};@{target|token_id}<br />
</pre><br />
<br />
Returns the distance (Chebyshev) between the selected and target tokens and stores it in "HowFarAway".<br />
<br />
<pre><br />
--SelectedDudes|getselected<br />
</pre><br />
<br />
If 5 tokens were selected, 6 variables would be created: SelectedDudesCount (with a value of 5), SelectedDudes1, SelectedDudes2, SelectedDudes3, SelectedDudes4, SelectedDudes5.<br />
<br />
=== Information Request (--i) ===<br />
<br />
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.<br />
<br />
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.<br />
<br />
After the user has clicked the button and responded to the requests, ScriptCards will resume processing the script from where it left off.<br />
<br />
Here is an example “i” line:<br />
<br />
<pre><br />
--IScriptCards needs additional information to continue;Click to select a target and provide information|t;MyNewTarget;Missile1Target||q;MyNameIs;What is your name?<br />
</pre><br />
<br />
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.<br />
<br />
Supported information request types are “t” for target token, and “q” for query.<br />
<br />
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).<br />
<br />
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:<br />
<br />
<pre><br />
q;UserName;What is your name?|Fred|Bob|Sally|Nancy<br />
</pre><br />
<br />
Would have a dropdown menu with four choices.<br />
<br />
== Inline Formatting ==<br />
<br />
Inline formatting is processed on Direct Output lines only (--+ lines) and the following inline format markup is available:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Formatting Tags !! Description<br />
|-<br />
| [b]..[/b] || Bold the text between the markers <br />
|-<br />
| [i]..[/i] || Italicize the text between the markers <br />
|-<br />
| [u]..[/u] || Underline the text between the markers <br />
|-<br />
| [s]..[/s] || Strike-Thru the text between the markers <br />
|-<br />
| [c]..[/c] || Center alignment <br />
|-<br />
| [l]..[/l] || Left alignment <br />
|-<br />
| [r]..[/r] || Right alignment <br />
|-<br />
| [j]..[/j] || Full justification alignment <br />
|-<br />
| [#xxx]..[/#] or [#xxxxxx]..[/#] || Use a 3 or 6 digit hex code to colorize the text between the markers <br />
|-<br />
| [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, <code>[img width=128 height=128]</code> )<br />
|-<br />
| [button]caption::action[/button] || Create a button with the label "caption" that performs the action defined by "action". <br />
|-<br />
| [t] || Converted to HTML table tag. Text after the "t" will be included inside the tag (width, border, etc)<br />
|-<br />
| [/t] || Converted to HTML close table tag.<br />
|-<br />
| [tr] || Converted to HTML table row tag. Text after the "tr" will be included inside the tag<br />
|-<br />
| [/tr] || Converted to HTML close table row tag.<br />
|-<br />
| [td] || Converted to HTML table cell tag. Text after the "tr" will be included inside the tag<br />
|-<br />
| [/td] || Converted to HTML close table cell tag.<br />
|}<br />
<br />
== Variables ==<br />
<br />
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. While it is possible to assign both a string and a roll variable the same name, doing so will likely result in confusion when looking at the script later, so it is not recommended.<br />
<br />
String Variables are assigned with the --& statement and are referenced using [&variableName] notation.<br />
<br />
Roll Variables are assigned with the --= statement, and the assignment value is always processed by the ScriptCards Roll Processor (resolves dice rolls, etc.)<br />
<br />
There are a handful of variables assigned automatically when a ScriptCard is executed. These are all string variables, and are:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Variable !! Value<br />
|-<br />
| SendingPlayerID || Contains the object ID of the player that sent the macro<br />
|-<br />
| SendingPlayerName || Contains the display name of the player<br />
|-<br />
| SendingPlayerColor || Contains the color code associated with the player<br />
|-<br />
| SendingPlayerSpeakingAs || The contents of the "Speaking As" dropdown window<br />
|-<br />
| SendingPlayerIsGM || Contains 1 if the player is a GM, and 0 if the player is NOT a GM<br />
|}<br />
<br />
== Arrays ==<br />
<br />
Arrays are a special type of variable, and are managed by the function (<nowiki>--~</nowiki> command). All of the array function commands follow the same pattern:<br />
<br />
<pre>--~variableName|array;subcommand;arrayname;param1;param2;param3;...</pre><br />
<br />
Not all array commands return anything to "variableName". The function table above will specify the return type of the command if any.<br />
<br />
There are a couple of different ways to create an array:<br />
<br />
The '''define''' array subcommand creates (or recreates) an array and assigns it values - one for each included parameter after the array name. For example:<br />
<br />
<pre>--~|array;define;Fruits;mango;peach;strawberry;apricot;banana;apple</pre><br />
<br />
will create an array called '''Fruits''' with 6 elements in the order listed in the command (mango, peach, etc.)<br />
<br />
You can also use two other subcommands to create arrays based on tokens:<br />
<br />
<pre>--~Count|array;pagetokens;Everybondy;@{selected|token_id}</pre><br />
<br />
and<br />
<br />
<pre>--~Count|array;selectedtokens;Selected</pre><br />
<br />
In both cases, arrays of tokens will be created, and a string variable called "Count" will be set to the number of tokens in the array. The '''pagetokens''' command returns (by default) all of the tokens on the page that contains the token passed as the parameter after the array name. You can filter the tokens that "pagetokens" includes in the array by appending an optional parameter describing the type of token you are looking for:<br />
<br />
<pre>--~Count|array;pagetokens;Everybondy;@{selected|token_id};npc</pre><br />
<br />
Will return only tokens on the page that represent characters that do not have a ''controlledby'' parameter set. The available options are "all" (default), "char", "graphic", "pc", and "npc".<br />
<br />
The '''selectedtokens''' command returns an array with all of the tokens that were selected when the script was called.<br />
<br />
You can also use an arbitrary string to create an array, specifying a delimiter with the '''fromstring''' command:<br />
<br />
<pre><br />
--&names|Fred<br />
--&names|+,Sally<br />
--&names|+,Ted<br />
--&names|+,Joyce<br />
--~|array;fromstring;,;[&names]<br />
</pre><br />
<br />
The above example builds a comma-separated string and then uses "fromstring" to create an array with 4 elements from it, specifying the comma as the delimiter.<br />
<br />
Finally, you can use the '''statusmarkers''' command to create an array with one entry for each active status marker on a specified token:<br />
<br />
<pre>--~|array;statusmarkers;Conditions;@{selected|token_id}</pre><br />
<br />
will create an array with one entry for each status active on the selected token. The array elements will be the internal name of the status (if you are using custom status marker packs, the names will be specified in the marker pack).<br />
<br />
'''Traversing Arrays'''<br />
<br />
Each array keeps track of an internal index position (starting at 0). Several commands let you manage this index:<br />
<br />
*'''getindex''' returns the current index value<br />
*'''setindex''' sets the index to the specified location in the array<br />
*'''getlength''' returns the number of elements in the array<br />
*'''indexof''' returns the index location of the specified element<br />
<br />
Other commands let you retrieve values from the array:<br />
<br />
*'''getfirst''' sets the index to 0 and returns the value at that position<br />
*'''getnext''' advances the index by 1 and returns the new current value<br />
*'''getprevious''' reduces the index by 1 and returns the new current value<br />
*'''getlast''' sets the index to the last elements in the array and returns the new current value<br />
<br />
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.<br />
<br />
'''Manipulating Array Elements'''<br />
<br />
Several array commands deal with inserting, removing, and modifying elements:<br />
<br />
*'''add''' works just like define, except that it takes an existing array and adds elements to it based on the passed parameters<br />
*'''remove''' looks for items matching each passed parameter and removes them from the indicated array if they exist<br />
*'''removeat''' allows you to specify an index location in the array and remove the element at that position<br />
*'''replace''' searches an array for a value and replaces all occurrences of it with a new value (if found)<br />
*'''sort''' sorts the elements in the array in ascending order<br />
*'''strinfigy''' returns a string variable that includes each array element separated by semicolons (;) <br />
<br />
'''Referencing Array Elements'''<br />
<br />
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.<br />
<br />
<pre><br />
!script {{<br />
--~dummy|array;pagetokens;myarray;@{selected|token_id}<br />
--~count|array;getcount;myarray<br />
--+Total:|There are [&count] graphical objects on the page<br />
--~testvar|array;getfirst;myarray<br />
--:loop|<br />
--+Value|[*[&testvar]:character_name]<br />
--~testvar|array;getnext;myarray<br />
--?[&testvar] -ne ArrayError|loop<br />
--+Loop1|Is Done!<br />
}}<br />
</pre><br />
<br />
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:<br />
<br />
<pre><br />
!script {{<br />
--~dummy|array;pagetokens;myarray;@{selected|token_id}<br />
--~count|array;getcount;myarray<br />
--+Total:|There are [&count] graphical objects on the page<br />
--%loopCounter|1;[&count]<br />
--+Value|[*[@myarray([&loopCounter])]:character_name]<br />
--%|<br />
--+Loop|Is Done!<br />
}}<br />
</pre><br />
<br />
This line : <nowiki>--+Value|[*[@myarray([&loopCounter])]:character_name]</nowiki> uses [@arrayName(index)] format (inside a [*characterid:attribute] syntax) to perform the same task as running through the loop with the index.<br />
<br />
(Note: Additional examples are on the way...)<br />
<br />
== For...Next Loops ==<br />
<br />
For...Next loops in ScriptCards are supported with the with the --% statement type. A loop is defined by starting off with:<br />
<br />
<pre><br />
--%LoopCounter|<start>;<end>;[step]<br />
</pre><br />
<br />
The start and end values are required, while the step parameter is optional. If the step is omitted, it will be assumed to be 1. A string variable named after the line tag ("LoopCounter" in the case above) will be created and will hold the current iteration value for the loop. Here is a real example:<br />
<br />
<pre><br />
--%LoopCounter|1;10;1<br />
</pre><br />
<br />
This will begin a loop identified by "LoopCounter" that will start at 1, increasing by 1 each iteration (the step) until it has completed 10 executions.<br />
<br />
The "next" statement is simply <code>--%|</code>, with no tag or parameters. This indicates to ScriptCards that it should increment the counter and go back to the beginning of the loop. Extending the example above:<br />
<br />
<pre><br />
!script {{<br />
--%LoopCounter|1;10;1<br />
--=Roll|1d20<br />
--+Loop|Counter is [&LoopCounter], roll was [$Roll]<br />
--%|<br />
}}<br />
</pre><br />
<br />
The <code>--%!|</code> sequence will break out of the loop, no matter how many iterations are remaining.<br />
<br />
The % and %! character sequences can also be used as part of a 1.2.1+ non-branching conditional to continue or break the loop:<br />
<br />
<pre><br />
--?"X[&RollInto]X" -eq "XX"|%<br />
</pre><br />
<br />
In this example, if the string variable RollInfo is empty, the loop will return to the top and continue with the next iteration, while:<br />
<br />
<pre><br />
--?"X[&RollInto]X" -eq "XX"|%!<br />
</pre><br />
<br />
Would cause the whole loop to end if the condition were true.<br />
<br />
== Referencing ==<br />
<br />
=== Roll Variables===<br />
<br />
Roll Variables can be referenced from the content portion of any line type, and from the tag portion of conditional statements. The referenced value is replaced when the line is executed.<br />
<br />
There are several modifiers that can be used to reference parts of a roll:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Modifier !! Meaning<br />
|-<br />
| No modifier || In a Direct Output Line (<nowiki>--+</nowiki>), GM Output Line (<nowiki>--*</nowiki>), or String Assignement (<nowiki>--&</nowiki>), 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<br />
|-<br />
| .Total || The end result of the roll equation. Formatting rules for "No Modifier" apply based on line type. <br />
|-<br />
| .Raw || The total value of the roll variable without any formatting, no matter what kind of line the reference is used in.<br />
|-<br />
| .Base || The cumulative result of any dice rolled in the Roll Text (Numeric modifiers are not included) <br />
|-<br />
| .Ones || The number of dice in the roll that came up as 1s <br />
|-<br />
| .Aces || The number of dice in the roll that came up as the maximum number on the die <br />
|-<br />
| .Odds || The number of dice in the roll that came up with an odd number <br />
|-<br />
| .Evens || The number of dice in the roll that came up with an even number <br />
|-<br />
| .RollText || The raw text of the roll that was use to generate the results <br />
|-<br />
| .Text || A text representation of the results of the roll, including the numbers rolled for each die <br />
|-<br />
| .tableEntryText || The text portion of the result of a table roll<br />
|-<br />
| .tableEntryImgURL || The image source portion of the result of a table roll<br />
|-<br />
| .tableEntryValue || If the tableEntryText is purely numeric, will contain the numeric value<br />
|}<br />
<br />
=== String Variables ===<br />
<br />
To reference a string variable, use the notation [&variablename]. String variables can be referenced in direct output, roll variable assignment, and string variable assignment statements.<br />
<br />
=== Character/Token Attributes ===<br />
<br />
A character or token attribute can be referenced from content portion of any type of line and is substituted when the line is executed. The general format for referencing a character attribute is [*ID:attribute]. ID can be a token ID or a character ID (these start with a dash). Additionally if you have specified a sourceToken or targetToken, you can substitute "S" or "T" for the ID (for example [*S:npc_type] will retrieve the npc_type attribute from the source token.<br />
<br />
By default, all attribute references will be pulled from the '''''character''''' object that the ID represents (either directly or by being a Token ID that represents a character).<br />
<br />
Keep in mind, that if you want to access the "max" of a character attribute (for example, the max hit points), then you cannot trust the name that your roll20 character sheet shows you when you hover your mouse over the max hit points. For example, this reference will not work: [*S:hp_max]. Instead, you need to use this reference: [*S:hp^].<br />
<br />
If your ID refers to a token, token attributes can be accessed by preceding the attribute name with "t-", for example [*S:t-aura1_radius]. Supported token attributes are:<br />
<br />
{|<br />
| t-name || t-id || t-statusmarkers || t-bar1_value<br />
|-<br />
| t-bar1_max || t-bar2_value || t-bar2_max || t-bar3_value<br />
|-<br />
| t-bar3_max || t-top || t-left || t-width<br />
|-<br />
| t-height || t-rotation || t-layer || t-aura1_radius<br />
|-<br />
| t-aura1_color || t-aura2_radius || t-aura2_color || t-aura1_square<br />
|-<br />
| t-aura2_square || t-tint_color || t-light_radius || t-light_dimradius<br />
|-<br />
| t-light_angle || t-light_losangle || t-light_multiplier || t-light_otherplayers<br />
|-<br />
| t-light_hassight || t-flipv || t-fliph || t-controlledby<br />
|-<br />
| t-_cardid || t-_pageid || t-imgsrc || t-bar1_link<br />
|-<br />
| t-bar2_link || t-bar3_link || t-represents || t-layer<br />
|-<br />
| t-isdrawing || t-name || t-gmnotes || t-showname<br />
|-<br />
| t-showplayers_name || t-showplayers_bar1 || t-showplayers_bar2 || t-showplayers_bar3<br />
|-<br />
| t-showplayers_aura1 || t-showplayers_aura2 || t-playersedit_name || t-playersedit_bar1<br />
|-<br />
| t-playersedit_bar2 || t-playersedit_bar3 || t-playersedit_aura1 || t-playersedit_aura2<br />
|-<br />
| t-lastmove || t-adv_fow_view_distance || t-has_bright_light_vision || t-has_night_vision<br />
|-<br />
| t-night_vision_distance || t-emits_bright_light || t-bright_light_distance || t-emits_low_light<br />
|-<br />
| t-low_light_distance || t-has_limit_field_of_vision || t-limit_field_of_vision_center || t-limit_field_of_vision_total<br />
|-<br />
| t-has_limit_field_of_night_vision || t-limit_field_of_night_vision_center || t-limit_field_of_night_vision_total || t-has_directional_bright_light<br />
|-<br />
| t-directional_bright_light_center || t-directional_bright_light_total || t-has_directional_dim_light || t-directional_dim_light_center<br />
|-<br />
| t-directional_dim_light_total || t-lightColor || || |<br />
|}<br />
<br />
'''''It is important to note that some attributes names on tokens have corresponding attribute names on characters, which represent different values. For example, [*T:id] returns the character ID, while [*T:t-id] returns the token ID.'''''<br />
<br />
=== Subroutine Parameters ===<br />
<br />
When using a gosub statement (-->) or a conditional marked as a gosub (prefixing the label with a > character), you can pass any number of parameters separated by semicolons (;) that the code in the subroutine can utilize.<br />
<br />
Subroutine parameters are numbered starting at 1, and are accessed by using the notation [%number%], so the first parameter is [%1%], the second is [%2%], etc.<br />
<br />
Parameter substitution happens on all line types, and happens prior to character attribute references or roll variable substitution.<br />
<br />
=== Campaign Attribute ===<br />
You can retrieve properties of the API's Campaign object with the [*C:attributename] syntax. For example, [*C:playerpageid] will retrieve the current player ribbon page from the Campaign object.<br />
<br />
=== Page Attributes ===<br />
If you have set the '''activepage''' parameter, you can retrieve page-related properties with the [*P:attributename] syntax, including the page's UDL parameters.<br />
<br />
=== Repeating Section Values ===<br />
<br />
You can reference repeating attribute data using the syntax [*R:attributename] syntax (similar to referencing standard character attributes). The currently active repeating row information will be used to retrieve attribute values. You can also retrieve the full attribute name for a repeating row attribute by using the [*R>attributename] notation. This is useful to pass to things like chatsetattr.<br />
<br />
=== Array Elements ===<br />
After an array has been declared, the elements can be referenced with [@arrayName(index)]. Array indices start at 0.<br />
<br />
== Deferred Resolution for Meta Scripts ==<br />
<br />
As of 1.2.9, ScriptCards supports a deferral character for use when calling another API script with via the --@ statement, to defer processing of meta script references so they get processed prior to the sub-API call insted of prior to ScriptCards execution. To defer this processing for meta script (SelectManager, Fetch) by inserting a deferral character into the meta call. For example, if I want to have ScriptCards call TokenMod as if the token for "Quej Gr'stra" (yes, I let Roll20 name my test NPCs) I could use something like this:<br />
<br />
--@token-mod|{^& select Quej Gr'stra} _on showname<br />
<br />
The "^" in between { and & will prevent SelectManager from seeing the call when the ScriptCard script is processed, but the --@ statement will remove the deferral character so the command that will be sent by ScriptCards is:<br />
<br />
!token-mod {& select Quej Gr'stra} --on showname<br />
<br />
With the deferral character removed, SelectManager will see the {& select ...} and do its magic.<br />
<br />
While the default deferral character is "^", the deferral character is a setting that can be changed:<br />
<br />
--#deferralcharacter|%<br />
<br />
Will make % the deferral character for future --@ statements in the running script.<br />
<br />
There are currently three supported Meta script structures: {^&...} for SelectManager, @^(...) and *^(...) for fetch, where the ^ in the structures here represents the placement of the deferral character.<br />
<br />
== Arrays ==<br />
<br />
Arrays are a new data type introduced in version 1.1.12 of ScriptCards, and are manipulated with associated function (--~) commands.<br />
<br />
* Arrays are a lists of strings. Items in an array cannot contain the semi-colon (;) character, as that is used to separate parameters in the function code that deals with arrays.<br />
* Arrays are accessed via the --~ script command. In some cases, the value of the tag (variable name) for array commands is not used, and can be a dummy value or simply omitted. I have omitted them in the statements below.<br />
* All commands that DO return a value return string values, even if the content is numeric.<br />
* If a command returns a value and there is some sort of reason that it isn't an array value, you will get "ArrayError" in the return value. This can happen if you reach the end of an array while stepping through it, for example, so checking for "ArrayError" can serve as the end condition for a loop.<br />
* Each array keeps track of its current index, allowing you to step forward and backwards through arrays.<br />
* Any number of arrays can be defined.<br />
* Unlike string variables and roll variables, array variables cannot (currently) be referenced directly. It is necessary to use the function (--~) syntax to manipulate arrays and get values from them as strings for use in other parts of your script.<br />
<br />
<br />
== Reentrant Scripts ==<br />
<br />
Reentrant scripts allow you to create buttons in your script code that will re-execute the script at a given label within the code. If you set the reentrant setting (--#reentrant|somevalue) to a non-zero value, your setting and variable information will be preserved between executions. Reentrant script can be used to present menus or choices and then continue acting.<br />
<br />
Reentrant buttons are created with the [rbutton]Caption::ReentryLabel;Parameter[/rbutton] construct. The caption will be displayed on the generated button. ReentryLabel is the name of a label in your script that the button will jump to when clicked, and Parameter will be passed in as a string value called "reentryval".<br />
<br />
Example:<br />
<pre><br />
!script {{<br />
--#reentrant|testing<br />
--=Roll|1d20<br />
--+Roll|[$Roll]<br />
--&String|That was a [$Roll.Raw]!<br />
--~x|array;define;MyArray;Apple;Banana;Orange<br />
--+Try it|[rbutton]Hello!::EXEC_PC_SPELL;9[/rbutton]<br />
--X|<br />
<br />
--:EXEC_PC_SPELL|<br />
--+ReentryVal|[&reentryval]<br />
--+The value of Roll is|[$Roll]<br />
--+Value of String|[&String]<br />
--+Array|[@MyArray(0)]<br />
--X|<br />
}}<br />
</pre><br />
<br />
This script sets up some variables and then displays a button labeled "Hello!". If the user clicks the button, the script will be re-entered starting at the "EXEC_PC_SPELL", which will display the content of the variables from the original execution.<br />
<br />
'''''Note: This section needs to be expanded upon'''''<br />
<br />
== Procedure Libraries ==<br />
<br />
You can now create handouts in your game in Roll 20 with the name format "ScriptCards Library NAME", where name is a name you assign to the library. Library names are case sensitive. It is my hope that the more proficient ScriptCards scripters out there will provide procedure libraries (or procedures that can be included in libraries) for others to use to make their scripting life easier. Be they specific to a game system, or to a type of activity, I think a robust set of libraries that GMs could use to enhance their scripting capabilities would be very valuable to the community. Should such things begin to emerge, I’ll create a portion of the ScriptCards Wiki page to house them.<br />
<br />
To include one or more libraries in a script, use the +++libname+++ directive (does not need a -- line associated with it). Multiple library names can be specified by separating them with semicolons (i.e., +++General;dnd5elib;Colorize+++ would include three libraries (General, dnd5elib, and Colorize).<br />
<br />
Included libraries are separated from the main script code by the automatic inclusion of "--X|" before the first library is appended to the script, and all libraries are loaded at the end of the script before script processing takes place.<br />
<br />
Procedures and labels in libraries can be used just as if they were included in the body of your script. Note that this DOES mean that you could, technically, jump into a library with a direct branch (--^) or direct branch conditional, but I recommend using libraries to store reusable procedures.<br />
The Notes section of the library handout stores the library code, and is written just like any other ScriptCards code except:<br />
<br />
* They cannot use roll queries (?{Some Prompt:}) to get information from the user at execution time.<br />
* They cannot use @{} notation to access character and token information.<br />
<br />
Both of these limitation stem from the fact that Procedure Libraries are not processed by the chat server, which is what handles these items.<br />
<br />
Here is an example of handling damage modifications (resistance, vulnerability, and immunity) in D&D 5E with a library:<br />
<br />
<pre><br />
!script {{<br />
+++dnd5elib+++<br />
--#|Damage Modifiers Test<br />
--#targettoken|@{target|token_id}<br />
-->Lib5E_CheckDamageModifiers|ResistType;fire<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] fire damage<br />
<br />
-->Lib5E_CheckDamageModifiers|ResistType;cold<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] cold damage<br />
<br />
-->Lib5E_CheckDamageModifiers|ResistType;poison<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] poison damage<br />
<br />
-->Lib5E_CheckDamageModifiers|ResistType;acid<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] acid damage<br />
<br />
--X|<br />
}}<br />
</pre><br />
<br />
Library content (In a handout called “ScriptCards Library dnd5elib” NOTE: Paste into Notepad first and then paste into the handout in Roll20 to avoid bringing over HTML formatting from the web site):<br />
<br />
<pre><br />
--/|ScriptCards Library: dnd5elib version 0.0.1<br />
--/|Provides various utility procedures for D&D 5E games<br />
<br />
--/|Lib5E_CheckDamageModifiers handle damage resistance, vulnerability, and immunity. <br />
--/|Pass a string variable to be filled with a string to be appended to a dice roll and the damage type <br />
<br />
--:Lib5E_CheckDamageModifiers|damageVariableName;damageType<br />
--&[%1%]|<br />
--?"[*T:npc_vulnerabilities]" -inc "[%2%]"|>_Lib5E_IsVulnerable;[%1%]<br />
--?"[*T:npc_resistances]" -inc "[%2%]"|>_Lib5E_IsResistant;[%1%]<br />
--?"[*T:npc_immunities]" -inc "[%2%]"|>_Lib5E_IsImmune;[%1%]<br />
--<|<br />
<br />
--:_Lib5E_IsVulnerable| --&[%1%]| * 2 [Vulnerable] --<|<br />
--:_Lib5E_IsResistant| --&[%1%]| \ 2 [Resistant] --<|<br />
--:_Lib5E_IsImmune| --&[%1%]| * 0 [Immune] --<|<br />
</pre><br />
<br />
The idea is that the functions in the library create a string that can be appended to a roll to modify the output based on resistances, so you pass Lib5E_CheckDamageModifiers the name of the string variable you want to use and the damage type. The variable (ResistType in this case) will include either nothing, “* 2 [Vulnerable]”, “\ 2 [Resistant]”, or “* 0 [Immune]” which can be included in a roll assignment (--=) to modify the damage as appropriate. The order here might be important if an NPC is misconfigured to be both resistant and immune to the same damage type. Since immune is an absolute, having it last ensures that it will override resistant or vulnerable. A creature that is both vulnerable and resistant (again, misconfigured) will come back as resistant since that condition is checked after vulnerable.<br />
Some notes: I prefix my library labels with either “Lib5E_” or “_Lib5E_” as a clarity convention. This isn’t strictly necessary but you should be aware that if two libraries (or if your script and a library) define the same label, the last label defined will win. Since libraries are appended to the end of the script in the order you include them in the +++libname+++ directive, you can somewhat control this, but it is probably best to avoid re-declaring labels. <br />
<br />
In my case, items beginning with “Lib5E_” are intended to be called by scripts, while items beginning with “_Lib5E_” are intended to be used as subroutines by the “public” procedures. Of course, there is no reason you couldn’t call them directly.<br />
<br />
You might also note that I’ve included some library information in comment lines (--/|) at the top of the library. These are ignored by ScriptCards, and are a good way to convey requirements, parameters, usage information, etc.<br />
<br />
== Example Libraries ==<br />
<br />
=== dnd5elib ===<br />
<br />
[https://github.com/kjaegers/ScriptCards Download the dnd5elib Library from the ScriptCards GitHub]<br />
<br />
The '''dnd5elib''' library provides a collection of utility procedures that help simplify dealing with the D&D 5E Official Sheet. Some of the procedures in this library require '''chatsetattr''' to be installed in your game. This is a growing library, and currently only has a handful of routines. They are:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Procedure Name !! Notes<br />
|-<br />
| style="white-space:nowrap" | Lib5E_CheckDamageModifiers || This procedure can be used to evaluate vulnerabilities, resistances, and invulnerabilities on an NPC. After setting the --#target| parameters, pass the Lib5E_CheckDamageModifiers procedure a variable name (no reference information) and a damage type (i.e., fire, cold, bludgeoning, etc.) and a string variable with the name passed in as the first parameter will be created that contains text that can be included in a roll line (--=) in order to modify the roll as appropriate. For example, '''-->Lib5E_CheckDamageModifiers|ResistType;fire''' will check the current target character's attributes for "fire" and will either return an empty string (no references), "* 0 [Immune]" if the creature is immune, "\ 2 [Resistant]" if the creature is resistant, or "* 2 [Vulnerable]" if the creature is vulnerable to fire damage.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_DeductSpellSlot || Pass in a character_id and a slot level, and the script will expend one spell slot of that level, capping the value at 0 slots remaining. For Example '''<nowiki>-->Lib5E_DeductSpellSlot|@{selected|character_id};1</nowiki>''' to deduct a first level spell slot from the selected character.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_FindResource || Used to locate a resource value on a character. Pass in a character_id, a resource name, and two variable names. The procedure will check both repeating and non-repeating resources looking for a resource whose name matches what was passed in and return three variables. The first will be a string variable named for the 3rd parameter and contains the attribute name of the resource's "name" field. The second will be a string variable named after parameter 4 and contains the resource's value field attribute name, and the third variable is a Roll Variable, also named after the 4th parameter that contains the current resource value. Example: '''<nowiki>-->Lib5E_FindResource|@{selected|character_id};Crossbow bolts;ResName;ResValue</nowiki>''' will find "Crossbow bolts" as a resource on the character and return [&ResName] which is the name of the resource attribute, [&ResValue] which is the '''name of the attribute that stores the value''' and [$ResValue] which is the current numeric value of the resource.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Global_Attack_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Attack Modifiers (repeating_tohitmod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Bless" for 1d4 active and "Being Cool" for +2 active, I will get a return string " + 1d4 [Bless] + 2 [Being Cool]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Save_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Save Modifiers (repeating_savemod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Bless" for 1d4 active and "Being Cool" for +2 active, I will get a return string " + 1d4 [Bless] + 2 [Being Cool]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Skill_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Skill Modifiers (repeating_skillmod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Guidance" for 1d4 active and "Being Cool" for +2 active, I will get a return string " + 1d4 [Guidance] + 2 [Being Cool]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_AC_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Save Modifiers (repeating_savemod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Shield of Faith" with a value of 2 active, I will get a return string " + 2 [Shield of Faith]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Damage_Modifiers || Pass a character ID and TWO string variable to set the return value. The first string will be for normal damage, and the second will be the additional damage on a crit. This procedure will look through the Global Damage Modifiers (repeating_damagemod_*) for rows that are active (checked on the character sheet) and return two strings with the dice rolls and descriptions for them (for example, if I have "Sneak Attack" with a value of 1d6 normal and 1d6 critical damage active, I will get a return string " + 1d6 [Sneak Attack]" and another string of " + 1d6 [Sneak Attack CRIT]" that can be used in a dice rolls.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_DivineSmiteDice || Used to calculate the number of dice to be rolled for a paladin's Divine Smite. Pass a target token id, a spell slot level, and a string variable to be set to the dice roll amount based on the NPC_TYPE attribute of the target token. The returned variable will contain a dice roll (like "3d8" that can be used in a --= line)<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Character_Summary || Outputs a mini character sheet, including clickable buttons for attacks, actions, legendary actions, etc. Will automatically detect a PC vs NPC and output the appropriate sections.<br />
|}<br />
<br />
Due to formatting issues with the Wiki, the library code has been moved to a [https://gist.github.com/kjaegers/52f6049ddd257f0a1288aca4bbde13c5 GITHUB GIT]. Please view the GIST in raw mode and copy the text and paste it into a handout called "ScriptCards Library dnd5elib" in your Roll20 Game.<br />
<br />
== What to Know if you are Coming from PowerCards ==<br />
<br />
''Note: This section is a work in progress.''<br />
<br />
While ScriptCards and PowerCard have very similar output goals, their internals and use are quite different. The table below summarizes some of the major differences between the scripts.<br />
<br />
::{| class="wikitable"<br />
|-<br />
! PowerCards !! ScriptCards <br />
|-<br />
| With a handful of exceptions, all lines in a PowerCard macro are intended to produce a line of output on the final card. || With ScriptCards, ONLY the <code>--+</code> and <code>--*</code> statement types produces output <br />
|-<br />
| PowerCards lines begin with two dashes (<code>--</code>) followed by a unique tag name for the line, followed by a vertical bar and the content for the line. || ScriptCards lines begin with two dashes (<code>--</code>) followed by a '''statement type identifier''', which is a single character that identifies the type of line to the interpreter. This is followed by a tag (frequently optional), a vertical bar, and the parameters for the statement being executed.<br />
|-<br />
| PowerCard macros are always processed top to bottom. Lines can be hidden so they don't output anything, but there is no looping or branching (--SkipTo looks like a branch, but it just hides all of the lines until the referenced label. || ScriptCards scripts support true branching, including direct branching (<code>--^</code>) and procedure branching (<code>--></code>) and (<code>--<</code>). Procedures support parameters and a call stack so procedures can be nested to call other procedures.<br />
|-<br />
| All lines in a PowerCards macro need to have unique tags because PowerCards builds the card as a single JavaScript object using the tag names to store what will be displayed. This is why repeated tag names always result in the last one being shown. || ScriptCards tags do not need to be unique, and in the case of many line types are optional.<br />
|-<br />
| PowerCards conditionals result in either showing or hiding the line they are on. || ScriptCards conditionals '''''only''''' support branching as the result of the comparison. This branching can be direct (a GOTO) or procedural (a GOSUB) '''''NOTE: As of version 1.2.0, ScriptCards also supports roll/string variable assignment as a result of conditional evaluation'''''<br />
|-<br />
| PowerCards relies on the Roll20 [[Quantum Roll]] server and inline rolls for all dice functions || ScriptCards includes its own dice roll parser, and '''''does not support''''' inline rolls.<br />
|-<br />
| PowerCards RollIDs (often mistaken for variables) are assigned by analyzing the results of an inline roll, and cannot be referenced in other rolls, so you can't roll a <code>1d4</code> and then roll a <code>1d20</code> and add the <code>1d4</code> result because all of the rolls happen on the chat server before PowerCards gets the macro text. || ScriptCards supports two types of variables: Roll Variables and String Variables. Because ScriptCards uses its own roll parser and is not dependent upon the chat server, rolls and their results can be used in other rolls, math functions, output, etc.<br />
|}<br />
<br />
== Example Scripts ==<br />
<br />
Below are some sample scripts that utilize the various statement types in ScriptCards:<br />
<br />
=== Divine Smite ===<br />
<br />
This script will prompt the user for a spell slot level to expend on a divine smite. It will check the target's npc_type to see if it is an Undead or Fiend, which adds an additional d8 to the smite roll.<br />
<br />
[[File:ScriptCards Divine Smite.png|Divine Smite Script Output]]<br />
<br />
<pre><br />
!scriptcard {{<br />
--#title|Divine Smite<br />
--=DiceCount|?{Spell Slot Level?|1|2|3|4|5|6|7|8|9} + 1<br />
--=IsFiendOrUndead|0<br />
--?"@{target|npc_type}" -inc fiend|>IsBoosted<br />
--?"@{target|npc_type}" -inc undead|>IsBoosted<br />
--=TotalDice|[$DiceCount] + [$IsFiendOrUndead]<br />
--=SmiteRoll|[$TotalDice]d8<br />
--#emoteText|@{selected|token_name} smites @{target|token_name}<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
--+Smite|deals [$SmiteRoll] radiant damage.<br />
--X|<br />
<br />
--:IsBoosted|<br />
--=IsFiendOrUndead|1<br />
--<|<br />
}}<br />
</pre><br />
<br />
==== How It Works ====<br />
<br />
The first line sets the "title" card parameter to "Divine Smite".<br />
<br />
Line 2 Shows a query to the user asking for the spell slot level, adds one and stores the value in the "DiceCount" Roll Variable. The query/dropdown is generated by the chat server prior to the script being executed.<br />
<br />
Line 3 defaults the "IsFiendOrUndead" Roll Variable to 0.<br />
<br />
Lines 4 and 5 compare the target's "npc_type" attribute (passed by the chat server as text) to see if they include either "undead" or "fiend". If true, the IsBoosted subroutine will be called. No parameters are passed to this subroutine.<br />
<br />
Line 6 sets the "TotalDice" variable to the base (DiceCount) number plus the IsFiendOrUndead number, which will be a 0 or a 1.<br />
<br />
Line 7 calculates "SmiteRoll" by rolling a number of d8 equal to the "TotalDice" value.<br />
<br />
Lines 8-10 set the parameters for the emote, which appears above the card content. By setting the sourceToken and the targetToken, their icons will appear in the emote surrounding the text describing the action.<br />
<br />
Line 11 is the only line that actually produces output on the card. It results in "Smite deals # radiant damage".<br />
<br />
Line 12 ends the script execution, preventing the script from continuing and running the subroutines out of context.<br />
<br />
Lines 14-16 are the IsBoosted subroutine, starting with the :IsBoosted label. The IsFiendOrUndead variable is set to 1, and a return from subroutine is executed.<br />
<br />
=== Magic Missile ===<br />
<br />
This script demonstrates using a loop and calling a subroutine to fire a number of missiles determine by the spell slot level used to cast the spell.<br />
<br />
[[File:ScriptCards_MagicMissile_Fixed.png|Magic Missile Script Output]]<br />
<br />
<pre><br />
!scriptcard {{ <br />
--#title|Magic Missile<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
--=MissileCount|?{Spell Slot Level?|1|2|3|4|5|6|7|8|9} + 2<br />
--=DisplayCount|1<br />
--=MissileDamage|0<br />
--#leftsub|Slot level ?{Spell Slot Level?}<br />
--#rightsub|Ranged Attack<br />
--#emoteText|Fred uses a level ?{Spell Slot Level?} spell slot to fire [$MissileCount.Total] missiles of magical force!<br />
--:MissileLoop|<br />
-->FireMissile|<br />
--=DisplayCount|[$DisplayCount] + 1<br />
--?[$DisplayCount] -le [$MissileCount]|MissileLoop<br />
--+Total|Total damage is [$MissileDamage]<br />
--X|<br />
<br />
--:FireMissile|<br />
--=ThisMissile|1d4 + 1<br />
--=MissileDamage|[$MissileDamage] + [$ThisMissile]<br />
--+Missile|[$DisplayCount.Total] Hits for [$ThisMissile] [b]force[/b] damage<br />
--<|<br />
}}<br />
</pre><br />
<br />
==== How It Works ====<br />
<br />
Lines 1-3 set the card title, the source token and the target token. Setting these tokens causes their icons/avatars to appear in the Emote section of the card.<br />
<br />
Line 4 asks the user what spell slot level they wish to use to cast magic missile. The number of missiles fired is equal to 2 plus the spell level, and this is stored in the MissileCount variable.<br />
<br />
Line 5 stores a 1 in the DisplayCount variable. This will be used to control the loop to determine the number of missiles fired and the missile number when displaying damage rolls.<br />
<br />
Line 6 initializes MissileDamage to 0<br />
<br />
Line 7 sets the left subtitle to the text "Slot Level #", where # is the spell slot level being used.<br />
<br />
Line 8 sets the right subtitle to the text "Ranged Attack".<br />
<br />
Line 9 sets the emoteText parameter with a description of the action, including the slot level and number of missiles fired.<br />
<br />
Line 10 is a label for the missile firing loop<br />
<br />
Line 11 Calls the "FireMissile" subroutine<br />
<br />
Line 12 increases the DisplayCount variable by 1<br />
<br />
Line 13 Checks to see if there are still missles to fire (DisplayCount <= MissileCount) and if so branches to MissileLoop<br />
<br />
Line 14 Displays the total damage dealt by the spell.<br />
<br />
Line 15 stops execution of the script to prevent out of context execution of the subroutine.<br />
<br />
Lines 76-21 are the FireMissile subroutine, beginning with the FireMissile label. The 1d4+1 is rolled and assigned to "ThisMissile". The result is added to the existing MissileDamage total, and a line for the current missile is displayed with the missile number and the damage for the missile.<br />
<br />
=== Longsword Attack ===<br />
<br />
This script demonstrates a standard 5E D&D melee weapon attack, including detection of misses, fumbles, hits, and critical hits. If installed, alterbars is used to decrement the target's BAR3 value by the damage dealt.<br />
<br />
[[File:ScriptCards Longsword.png|Longsword Script Output]]<br />
<br />
<pre><br />
!scriptcard {{<br />
--#title|Longsword<br />
--#leftsub|Melee Attack<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
--#emoteText|@{selected|token_name} attacks @{target|token_name}<br />
--=TargetAC|@{target|npc_ac}<br />
--?[$TargetAC.Total] -gt 0|DoneWithAC<br />
--=TargetAC|@{target|ac}<br />
--:DoneWithAC|<br />
--=AttackRoll|1d20 + @{selected|strength_mod} [STR] + @{selected|pb} [PROF]<br />
--+Attack|@{selected|token_name} rolls [$AttackRoll] vs AC [$TargetAC].<br />
--?[$AttackRoll.Base] -eq 20|Crit<br />
--?[$AttackRoll.Base] -eq 1|Fumble<br />
--?[$AttackRoll.Total] -ge [$TargetAC.Total]|Hit<br />
--+Miss|The attack missed.<br />
--^Final|<br />
<br />
--:Fumble|<br />
--+Fumble!|The attack went horribly wrong.<br />
--^Final|<br />
<br />
--:Hit|<br />
--=Damage|1d8 + @{selected|strength_mod} [STR]<br />
--+Hit!|The attack hit @{target|token_name} for [$Damage] slashing damage.<br />
--@alter|_target|@{target|token_id} _bar|3 _amount|-[$Damage]<br />
--^Final|<br />
<br />
--:Crit|<br />
--=Damage|1d8 + @{selected|strength_mod} [STR] + 1d8 [CRIT]<br />
--+Critical Hit!|The attack hit @{target|token_name} for [$Damage] slashing damage.<br />
--@alter|_target|@{target|token_id} _bar|3 _amount|-[$Damage]<br />
<br />
--:Final|<br />
}}<br />
</pre><br />
<br />
==== How it Works ====<br />
<br />
In lines 1-5, we set the title, subtitle, and emote text along with the tokens for the emote area.<br />
<br />
Lines 6-9 allow us to determine the AC of the target. On the 5E Roll20 sheet, NPCs armor class is stored in "npc_ac", while PCs armor class is in "ac". First we grab npc_ac and if it is zero, we check AC.<br />
<br />
Line 10 rolls the attack roll, rolling 1d20 and adding the attacker's strength modifier and proficiency bonus<br />
<br />
Line 11 displays the result of the attack roll on the card<br />
<br />
Lines 12-14 determine what kind of result the attack had. If the .Base value of the roll was 20, we branch to "Crit". If it was 1, we branch to "Fumble". If the .Total value of the roll was greater than or equal to the AC that was determined in Lines 6-9, we branch to Hit.<br />
<br />
Assuming we didn't branc anywhere, the result of the attack was a miss, so we display that on line 15 and then branch to "Final"<br />
<br />
This is followed by three branch segments, :Fumble, :Hit, and :Crit. A fumble displays a text message and branches to :Final.<br />
<br />
On a hit or a crit, we roll Damage (adding additional damage dice on a crit). We display a "Hit!" or "Critical Hit!" message and then make an API call to AlterBars, passing it the token id, bar we want to modify (3 in this case), and the amount we want to modify by the Damage value.<br />
<br />
=== Party Health Status ===<br />
<br />
This example calculates the current Hit Points remaining and HP percentage for each character and creates a color-coded display with the current party status.<br />
<br />
[[File:ScriptCards Party Health.png]]<br />
<br />
<pre><br />
!scriptcard {{<br />
--#title|Party Status<br />
--#titleCardBackground|#33CC33<br />
--#oddrowbackground|#bfee90<br />
--#evenrowbackground|#90eebf<br />
-->HealthCheck|@{Quej Grastra|character_id}<br />
-->HealthCheck|@{Brim Cheuto|character_id}<br />
-->HealthCheck|@{Odug Ututees|character_id}<br />
--X|End of card Execution<br />
<br />
--:HealthCheck|<br />
--=HealthPerc|[*[%1%]:hp] / [*[%1%]:hp^] * 100 \ 1<br />
--=HealthColor|000000<br />
--?[$HealthPerc.Total] -gt 50|HealthSkip<br />
--=HealthColor|FF0000<br />
--:HealthSkip|<br />
--+[*[%1%]:character_name]|has [#[$HealthColor.RollText]][*[%1%]:hp] of [*[%1%]:hp^][/#] HP [R]([$HealthPerc.Total]%)[/R]<br />
--<|End of HealthCheck<br />
}}<br />
</pre><br />
<br />
==== How it Works ====<br />
<br />
Lines 1-4, we set the card title, and set the title background and row background colors to shades of green.<br />
<br />
Lines 5-7 make gosub calls the the "HealthCheck" subroutine, passing in the character ID of each of the named characters (these are the names of the characters in my test game)<br />
<br />
Line 8 terminates the script execution.<br />
<br />
The remaining lines of the script are the HealthCheck subroutine, which works like this:<br />
<br />
Line 10 is the subroutine label (:HealthCheck)<br />
<br />
Line 11 uses the character id passed as a parameter and combines it with character attribute lookup *(...) to retrieve the value of "hp" and "hp<nowiki>^</nowiki>" for the character. The <nowiki>^</nowiki> character is used to specify that we want the MAX value for this attribute for the second call. We divide these two numbers and multiple by 100 to get a percentage. Finally, we use integer division by 1 to round the percentage and drop the decimals. The end result gets stored in the HealthPerc roll variable.<br />
<br />
Line 12 defaults to color of the health text to black<br />
<br />
Line 13 check to see if the health percentage is greater than 50. If so, it branches to HealthSkip, preventing the script from executing line 13.<br />
<br />
Line 14 sets the color of the health text to red<br />
<br />
Line 15 is the label that will be branched to from Line 13 to skip the red coloring<br />
<br />
Line 16 again uses character attribute substitution and the passed parameter value to output a display line containing the character name, the colorized health total, and the percentage value. The percentage is right-justified.<br />
<br />
Line 17 returns from the HealthCheck subroutine.<br />
<br />
=== Expanded Magic Missile Script ===<br />
<br />
This is the expanded and enhanced version of the Magic Missile script covered in {{yt|watch?v=u50xvNzS9Zk | this video}}. It includes visual and audio effects, checking and deducting spell slots, and applying damage using either Token-Mod or Alterbars.<br />
<br />
<pre><br />
!scriptcard {{ <br />
--#title|Magic Missile<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
<br />
-->GetAndCheckSlotInformation|<br />
<br />
--=MissileCount|[$SlotLevel] + 2<br />
--=DisplayCount|1<br />
--=MissileDamage|0<br />
--#leftsub|Slot level [$SlotLevel]<br />
--#rightsub|Ranged Attack<br />
--#emoteText|@{selected|character_name} uses a level [$SlotLevel.Total] spell slot to fire [$MissileCount.Total] missiles of magical force!<br />
<br />
--:MissileLoop|<br />
-->FireMissile|<br />
--=DisplayCount|[$DisplayCount] + 1<br />
--?[$DisplayCount] -le [$MissileCount]|MissileLoop<br />
--+Total|Total damage is [$MissileDamage]<br />
-->DeductSpellSlot|<br />
--#rightsub|Level [$SlotLevel] Left: [$SlotsRemaining] <br />
-->PlayEffects|none;burst-smoke;beam-magic;spell_01<br />
-->ApplyDamageTokenmod|@{target|token_id};3;-[$MissileDamage]<br />
-->ApplyDamageAlterbars|@{target|token_id};3;-[$MissileDamage]<br />
--X|<br />
<br />
--:FireMissile|<br />
--=ThisMissile|1d4 + 1<br />
--=MissileDamage|[$MissileDamage] + [$ThisMissile]<br />
--+Missile|[$DisplayCount.Total] Hits for [$ThisMissile] [b]force[/b] damage<br />
--<|<br />
<br />
--:GetAndCheckSlotInformation|<br />
--=SlotLevel|?{Spell Slot Level?|1|2|3|4|5|6|7|8|9}<br />
--=SlotsTotal|[*S:lvl[$SlotLevel]_slots_total]<br />
--=SlotsExpended|[*S:lvl[$SlotLevel]_slots_expended]<br />
--?[$SlotsExpended.Total] -ge [$SlotsTotal.Total]|NoSlotsLeft<br />
--<|<br />
<br />
--:NoSlotsLeft|<br />
--+|[*S:character_name] has no level [$SlotLevel.Total] spell slots available.<br />
--X|<br />
<br />
--:DeductSpellSlot|<br />
--=SlotsExpended|[$SlotsExpended] + 1<br />
--@setattr|_charid [*S:character_id] _lvl[$SlotLevel]_slots_expended|[$SlotsExpended] _silent<br />
--=SlotsRemaining|[$SlotsTotal] - [$SlotsExpended]<br />
--<|<br />
<br />
--:PlayEffects|Parameters are : source effect; target effect; line effect; sound effect<br />
--vtoken|@{selected|token_id} [%1%]<br />
--vtoken|@{target|token_id} [%2%]<br />
--vbetweentokens|@{selected|token_id} @{target|token_id} [%3%]<br />
--@roll20AM|_audio,play,nomenu|[%4%]<br />
--<|<br />
<br />
--:ApplyDamageTokenmod|Parameters are tokenid;bar#;amount<br />
--@token-mod|_ignore-selected _ids [%1%] _set bar[%2%]_value|[%3%]<br />
--<|<br />
<br />
--:ApplyDamageAlterbars|<br />
--@alter|_target|[%1%] _bar|[%2%] _amount|[%3%]<br />
--<|<br />
}}<br />
</pre><br />
<br />
[[Category:Featured articles]]</div>5004103https://wiki.roll20.net/Script:ScriptCardsScript:ScriptCards2021-09-28T16:54:51Z<p>5004103: /* Comment (--/) */</p>
<hr />
<div>{{revdate}}<br />
== Introduction ==<br />
'''ScriptCards''' provides a script interpreter that can be used to create powerful macros that display the results of player/NPC actions, or display other information in a pleasing visual format in your game's chat window. The scripting language contains variables (both dice-roll (enhanced numerics) and strings) as well, conditionals, branching, subroutines with parameters, and a set of built-in functions to simplify working with Roll20 information.<br />
{{script overview<br />
|name=ScriptCards<br />
|author={{user profile|2365448|Kurt J.}}<br />
|code=<br />
|version=1.4.0e<br />
|lastmodified=2021-09-24}}<br />
ScriptCards is not game-system specific, and can be used with any system/sheet. Near the end of this Wiki there is a section set aside for libraries that can implement system-specific tasks, with the hope that enthusiasts playing particular systems will create and share utility functions that can be utilized by the wider community.<br />
<br />
The default display style for ScriptCards output is similar to the format used to document player and NPC abilities in Dungeons and Dragons 4th Edition, but does not have any system ties to D&D4E.<br />
<br />
Current OneClick Version : 1.4.0e<br />
<br />
Current Development Version : 1.4.4<br />
<br />
'''''<big>Critically Important: ScriptCards does not use/parse inline rolls. ScriptCards includes its own built-in dice roll parser to allow for the use of variables inside dice rolls. As of version 1.2.3, ScriptCards will now take inline rolls and substitute the total result value in statement strings, meaning that you can utilize inline rolls but ScriptCards will only see the result of the roll, and not parse the roll components itself.</big>'''''<br />
<br />
* {{fpl|9752053/ ScriptCards thread}}<br />
** {{fpl|10000297/ Scritpcard API Working and Sharing}}<br />
* https://github.com/kjaegers/ScriptCards/tree/main/ScriptCards_API - GitHub repository for source before the one-click version is updated.<br />
* {{yt.be|hyR7Jnq4mQM ScriptCards Intro}} 45min, Jan 2021<br />
* {{yt.be|u50xvNzS9Zk ScriptCards Magic Missile Deep Dive}} 39min, Feb 2021<br />
<br />
<br />
__TOC__<br />
=== Is ScriptCards Related to [[PowerCards]]? ===<br />
<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
Check the '''[[#What to Know if you are Coming from PowerCards|What to Know if you are Coming from PowerCards]]'''-section for a comparison table between the two scripts.<br />
<br />
== What is a ScriptCard Script ==<br />
<br />
A ScriptCard Script is text written into the chat window (either typed directly, pasted, or run via a macro) that will produce a card of information in the [[text Chat|chat window]]. A ScriptCard Script is composed of an [[API]] command: <code><nowiki>!scriptcard {{ }}</nowiki></code> enclosing any number of lines that determine the output that will be added to the card. At it simplest, the following macro:<br />
<br />
<pre>!scriptcard {{ }}</pre><br />
<br />
Will produce just a title card that displays “ScriptCards” as the name:<br />
<br />
[[File:Scriptcard blank.png]]<br />
<br />
Of course, this is just the simplest type of macro and isn’t very useful. In order to produce useful output, we need to include lines between the <code><nowiki>{{</nowiki></code> and <code><nowiki>}}</nowiki></code> that direct the API script as to what it should do.<br />
<br />
== Structure of a ScriptCard Line ==<br />
<br />
All ScriptCard lines begin with two dashes, followed by an ''statement identifier character'' that lets ScriptCards what type of line it is. There are several of these, and they are detailed in the next section. After the line type identifier, a Tag name 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.<br />
<br />
Following the Tag is a vertical bar, and then the content of the line itself. Again, each type of line might interpret this content differently.<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Identifier !! Statement Type !! Tag !! Content !! Notes<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--/</nowiki> || Comment || unused || unused || The <code>--/</code> 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--#</nowiki> || 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").<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--+</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--=</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--&</nowiki> || Assign String 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. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--@</nowiki> || 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 (i.e., [[TokenMod|!token-mod]], or [[ChatSetAttr|!setattr]], etc.)<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--:</nowiki> || 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<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--^</nowiki> || Branch To || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--></nowiki> || Call Procedure || 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<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--<</nowiki> || 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.<br />
|- <br />
| style="white-space:nowrap" | <nowiki>--?</nowiki> || Conditional Branch || Condition to be evaluated || True Branch Label<nowiki>|</nowiki>False Branch Label || The condition will be evaluated and execution will jump to one of the two indicated branches (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 included a semicolon separated list of parameters. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--s</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--l</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--v</nowiki> || 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+'''''<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--e</nowiki> || Echo to Chat || Name to send chat command as || Chat message to send || Variable substitution takes place on the tag and content.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--R</nowiki> || Retrieve Repeating Section Row information || "find", "first", or "next" || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--~</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--c</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--i</nowiki> || Information Request || User Prompt;Button Caption || InfoType;VariableName;ParameterText || See full documentation below.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--d</nowiki> || 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. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--%</nowiki> || 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. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--*</nowiki> || 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.<br />
|}<br />
<br />
== ScriptCard Statement Type Details ==<br />
The sections below detail the individual statement types supported by ScriptCards<br />
<br />
=== Comment (--/) ===<br />
<br />
A --/ statement is ignored by the ScriptCards parser. You can use this type of statement to add comments and informational text to your script. <br />
<br />
Example:<br />
<pre><br />
!script {{<br />
--/|Script Name : Fireball<br />
--/|Purpose : Allow the player to cast a fireball and blow stuff up!<br />
.<br />
.<br />
.<br />
}}<br />
</pre><br />
<br />
Using this style will ''sometimes'' work:<br />
<pre><br />
!script {{<br />
--/|When you have a very<br />
long comment, then<br />
you sometimes have<br />
to put it in multiple<br />
lines.<br />
.<br />
.<br />
.<br />
}}<br />
</pre><br />
But it's not recommended, because it can lead to unwanted behavior (like a mysterious line that appears on your output card, and only says: "IsRight").<br />
<br />
=== Set Parameter (--#) ===<br />
<br />
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.<br />
<br />
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.<br />
<br />
'''''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.'''''<br />
<br />
Examples:<br />
<pre><br />
--#title|Magic Missile<br />
--#leftsub|Level 1 Spell<br />
--#rightsub|Force Damage<br />
</pre><br />
<br />
The three examples above set the “title”, “leftsub”, and “rightsub” values for the card to the content value for the line. <br />
<br />
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.<br />
Settings Lines do not produce output lines on the card.<br />
<br />
The following settings are available (note that parameter names are ''not'' case sensitive):<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Name !! Effect/Use !! Default Value !! Type<br />
|-<br />
| 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<br />
|-<br />
| allowplaintextinrolls || If set to a non-zero value, plain character text in rolls will be copied to the roll text || 0 || Per-Line<br />
|-<br />
| bodyFontFace || Name of the font used in the card rows || Helvetica || Global<br />
|-<br />
| bodyFontSize || Size of the text in the card rows || 14px || Global<br />
|-<br />
| bodybackgroundimage || Specify an image (content for a CSS background-image tag) for the body area || none || Global<br />
|-<br />
| buttonBackground || Background color for buttons created with [button][/button] || #1C6EA4 || Per-Line<br />
|-<br />
| buttonBorderColor || Border (outline) color for buttons created with [button][/button] || #999999 || Per-Line<br />
|-<br />
| buttonFontFace || Font Family specifier for captions on buttons created with [button][/button] || Tahoma || Per-Line<br />
|-<br />
| buttonFontSize|| Text size for captions on buttons created with [button][/button] || x-small || Per-Line<br />
|-<br />
| buttonTextColor|| Text color of labels on buttons created with [button][/button] || #FFFFFF || Per-Line<br />
|-<br />
| 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<br />
|-<br />
| deferralcharacter || Changes the meta script deferral sequence to the specified value || ^ || Per-Line<br />
|-<br />
| diceFontColor|| Color of the dice created with the [d4] [d6], etc. formatting markers || #1C6EA4 || Per-Line<br />
|-<br />
| dicefontsize || Size of the dice created with the [d4] [d6], etc. formatting markers || 3.0em || Per-Line<br />
|-<br />
| 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<br />
|-<br />
| disablerollprocessing || If set to a non-zero value, --= lines will not process dice rolls strings || 0 || Per-Line<br />
|-<br />
| emoteBackground || Background color of the emote area || #f5f5ba || Global<br />
|-<br />
| emoteFont || Name of the font used in emote area (above the title of the output card) || Georgia || Global<br />
|-<br />
| emoteFontColor || Color of the font in the emote area || None (Empty) || Global<br />
|-<br />
| emoteFontSize || Size of the font used in the emote area || 14px || Global<br />
|-<br />
| emoteFontWeight || Font weight for the font in the emote area || bold|| Global<br />
|-<br />
| emoteState || If set to anything other than "visible", the emote portion of the card will not be displayed || visible || Global<br />
|-<br />
| emoteText || Text to display in the emote portion of the card || None (Empty) || Global<br />
|-<br />
| emotefont || Name of the font used in the emote text area || font-family: Georgia, serif; font-weight: bold; || Global<br />
|-<br />
| evenRowBackground || Hex code for the background color for even rows || #eeeeee || Per-Line<br />
|-<br />
| evenRowFontColor || Hex code for the text color for even rows || #000000 || Per-Line<br />
|-<br />
| evenrowbackgroundimage || Specify an image (content for a CSS background-image tag) for the even card rows || none || Per-Line<br />
|-<br />
| executionlimit || Maximum number of script lines the interpreter will try to execute. This prevents "infinite loop" sandbox crashes || 40000 || Global<br />
|-<br />
| hideCard || If set to any non-default value, the entire card output will be suppressed || 0 || Global<br />
|-<br />
| 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<br />
|-<br />
| 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<br />
|-<br />
| lineheight || Vertical size of each line on the output card || normal || Per-Line<br />
|-<br />
| nominmaxhighlight || If set to anything other than "0", rolls will not display crit/fumble/mixed highlight colors. || 0 || Per-Line<br />
|-<br />
| norollhighlight || If set to anything other than "0", rolls will not be formatted (plain numbers) but will still get a tooltip with details ('''''v1.3.6b+''''') || 0 || Per-Line<br />
|-<br />
| oddRowBackground || Hex code for the background color for even rows || #d0e4f5 || Per-Line <br />
|-<br />
| oddRowFontColor || Hex code for the text color for odd rows || #000000 || Per-Line<br />
|-<br />
| oddrowbackgroundimage || Specify an image (content for a CSS background-image tag) for the odd crd rows || none || Per-Line<br />
|-<br />
| reentrant || Used to name a script for rentrant button use || 0 || Global<br />
|-<br />
| 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)0 || Global<br />
|-<br />
| rollhilightlineheight || Determines the height of the hilight box placed around roll results ('''''1.4.2+''''') || 1.0em || Per-Line<br />
|-<br />
| roundUp || If set to a non-default value, integer division will round up instead of down || 0 || Per-Line<br />
|-<br />
| showfromfornonwhispers || If set to a non-zero value, will include the sender on cards that aren't whispered || 0 || Global<br />
|-<br />
| 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<br />
|-<br />
| subtitleFontColor || Color of the text in the subtitle areas || #FFFFFF || Global<br />
|-<br />
| subtitleFontFace || Name of the font used on the subtitle sections || Tahoma || Global<br />
|-<br />
| subtitleFontSize || Size of the subtitle font || 13px || Global<br />
|-<br />
| subtitleSeperator || The character(s) that will be placed between leftsub and rightsub || <nowiki>&#x2666</nowiki>; || Global<br />
|-<br />
| tableBorderRadius || CSS specifier for how rounded the borders of the output card are. Use "0px;" for square borders || 6px; || Global<br />
|-<br />
| tableShadow || CSS specifier for the drop shadow under the output card || 5px 3px 3px 0px #aaa; || Global<br />
|-<br />
| tablebgcolor || Background color of the whole card. '''''Normally not visible''''' || #EEEEEE || Global<br />
|-<br />
| tableborder || Color of the border that surrounds the whole card || 2px solid #000000; || Global<br />
|-<br />
| 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<br />
|-<br />
| timezone || IANA Specifier for the local time zone, used in system/date functions || merica/New_York || Per-Line<br />
|-<br />
| title || Text displayed in the title area of the card || ScriptCards || Global<br />
|-<br />
| titleCardBackground || A hex color code representing the background color of the title area. || #1c6ea4 || Global<br />
|-<br />
| titleFontColor || Color of the text on the card title || #FFFFFF || Global<br />
|-<br />
| titleFontFace || Name of the font used on the title area || Contrail One || Global<br />
|-<br />
| titleFontLineHeight || Line spacing on the title area || 1.2em || Global<br />
|-<br />
| titleFontSize || Size of the title font || 1.2em || Global<br />
|-<br />
| titlecardbackgroundimage || Specify an image (content for a CSS background-image tag) for the title card area || none || Global<br />
|-<br />
| titlecardbottomborder || Border CSS specifier for the bottom of the title card area || 2px solid #444444; || Global<br />
|-<br />
| titlecardgradient || If set to non-zero value, will place a vertical gradient on the title card area || 0 || Global<br />
|-<br />
| usehollowdice || If set to a non-zero value, the hollow/outline versions of the dice fonts will be used || 0 || Per-Line<br />
|-<br />
| whisper|| Comma separated list of who to whisper the output to. Use "gm" for [[GM|GMs]] and "self" for the sender || none || Global|}<br />
|}<br />
<br />
''Setting Lines do not produce output lines on the card''<br />
<br />
=== Direct Output (--+) ===<br />
<br />
A direct output line display 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.<br />
<br />
Examples of Direct Output lines:<br />
<pre><br />
--+Hello|World<br />
--+Attack|The monster rolls [$Attack] to hit!<br />
--+Damage|@{target|token_name} is hit for [$Damage] [#3333AA][b]frost[/b][/#] damage.<br />
</pre><br />
<br />
Direct Output lines support inline formatting, roll variable replacement, character attribute references, and procedure variables.<br />
<br />
=== GM Output (--*) ===<br />
<br />
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. <br />
<br />
Example:<br />
<pre><br />
--+PlayerLine|This line is shown on the public card<br />
--*GMLine|This line will only be shown to GMs, on a separate card.<br />
</pre><br />
<br />
=== Roll Variable Assignment (--=) ===<br />
<br />
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.<br />
<br />
'''''All components of a roll equation should be separated with spaces.'''''<br />
<br />
Examples:<br />
<pre><br />
--=MissileDamage|1d4 + 1<br />
--=Attack|1d20 + @{selected|strength_mod} [STR] + @{selected|pb} [PROF]<br />
</pre><br />
<br />
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. Text enclosed in square brackets ([]) is considered "flavor text" and will be added to the result text but does not impact the roll result.<br />
<br />
The following dice formats are supported:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Format Pattern !! Example !! Description<br />
|-<br />
| XdY || 3d8 || Simple format. Roll a Y-sided die X times<br />
|-<br />
| XdYkhZ || 2d20kh1 || Roll Y-sided die X times and keep the highest Z number of dice<br />
|-<br />
| XdYklZ || 4d6kl3 || Roll Y-sided die X times and keep the lowest Z number of dice <br />
|-<br />
| XdY>Z || 5d6>3 || Roll Y-sided die X times and count a 1 for each roll greater than Z <br />
|-<br />
| XdY<Z || 5d6<3 || Roll Y-sided die X times and count a 1 for each roll less than Z <br />
|}<br />
<br />
'''''Note: The dice formulae below are supported in the development version of ScriptCards and will be merged with the table above when activated on OneClick'''''<br />
::{| class="wikitable"<br />
|-<br />
! Format Pattern !! Example !! Description<br />
|-<br />
| 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<br />
|-<br />
| 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<br />
|-<br />
| 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)<br />
|-<br />
| 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<br />
|}<br />
<br />
The following operators are supported in a roll equation:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Operator !! Operation<br />
|-<br />
| + || Addition <br />
|-<br />
| - || Subtraction <br />
|-<br />
| * || Multiplication <br />
|-<br />
| / || Division <br />
|-<br />
| \ || Integer Division (Rounds down) <br />
|-<br />
| % || Modulo (Remainder of Divison)<br />
|}<br />
<br />
Roll Variables can be accessed at any time after they have been created by using the [$VariableName] format, with the following optional modifiers:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Modifier !! Meaning<br />
|-<br />
| No modifier || In a Direct Output Line (<nowiki>--+</nowiki>) 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<br />
|-<br />
| .Total || The end result of the roll equation as an unformatted number <br />
|-<br />
| .Base || The cumulative result of any dice rolled in the Roll Text (Numeric modifiers are not included) <br />
|-<br />
| .Ones || The number of dice in the roll that came up as 1s <br />
|-<br />
| .Aces || The number of dice in the roll that came up as the maximum number on the die <br />
|-<br />
| .Odds || The number of dice in the roll that came up with an odd number <br />
|-<br />
| .Evens || The number of dice in the roll that came up with an even number <br />
|-<br />
| .RollText || The raw text of the roll that was use to generate the results <br />
|-<br />
| .Text || A text representation of the results of the roll, including the numbers rolled for each die <br />
|-<br />
| .tableEntryText || The text portion of the result of a table roll<br />
|-<br />
| .tableEntryImgURL || The image source portion of the result of a table roll<br />
|-<br />
| .tableEntryValue || Numeric value of tableEntryText (via parseInt). If a non-numeric value, will be 0<br />
|-<br />
| .Raw || The total numeric result without any formatting, even if placed somewhere formatting would normally be done. <br />
|}<br />
<br />
Examples:<br />
<pre><br />
--+Total Damage|[$MissileDamage.Total] (roll was 1d4+1)<br />
--+Base Damage|[$MissileDamage.Base] (without the +1)<br />
--=Attack|1d20 + @{selected|strength_mod} [STR] + @{selected|pb} [PROF] + [$BlessBonus] [Bless]<br />
</pre><br />
<br />
In this case, 1d4 will be rolled and stored in “BlessBonus”, which can then be used in the Attack line.<br />
<br />
'''''Mathematical Functions in Roll Expressions '''''<br />
<br />
The ScriptCards roll parser works from left to right, always maintaining a current value and applying whatever comes next to the total. The following in-line functions to the roll parser. These are:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Expression !! Meaning<br />
|-<br />
| {ABS} || Absolute Value<br />
|-<br />
| {CEIL} || Ceiling value (round up to the next whole number)<br />
|-<br />
| {FLOOR} || Floor value (round down to the next whole number)<br />
|-<br />
| {ROUND} || Round value (round up if the decimal portion is greater than 0.5, otherwise round down)<br />
|-<br />
| {NEGATE} || Multiply the value by negative one.<br />
|-<br />
| {SQRT} || Take the square root of the running value. ('''''1.4.1+''''')<br />
|-<br />
| {SQUARE} || Square the running value. ('''''1.4.2+''''')<br />
|-<br />
| {CUBEROOT} || Take the cube root of the running value. ('''''1.4.2+''''')<br />
|-<br />
| {CUBE} || Cube the running value. ('''''1.4.2+''''')<br />
|-<br />
| {SIN} || Return the SIN of running value. ('''''1.4.2+''''')<br />
|-<br />
| {COS} || Return the COS of running value. ('''''1.4.2+''''')<br />
|-<br />
| {TAN} || Return the TAN of running value. ('''''1.4.2+''''')<br />
|-<br />
| {ASIN} || Return the ASIN of running value. ('''''1.4.2+''''')<br />
|-<br />
| {ACOS} || Return the ACOS of running value. ('''''1.4.2+''''')<br />
|-<br />
| {ATAN} || Return the ATAN of running value. ('''''1.4.2+''''')<br />
|}<br />
<br />
<br />
'''''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 <nowiki>[[ ]]</nowiki> 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.<br />
<br />
'''''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.<br />
<br />
'''Rolling on Rollable Tables'''<br />
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.<br />
<br />
''Roll Variable Lines do not produce output lines on the card.''<br />
<br />
=== String Variable Assignment (--&) ===<br />
<br />
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:<br />
<br />
<pre><br />
--&MyText|Hello<br />
</pre><br />
<br />
Here, we assign the text "Hello" to the string variable named MyText. You can also append text to a string variable by prefixing the content with a + sign:<br />
<br />
<pre><br />
--&MyText|+ World<br />
</pre><br />
<br />
If run after the statement above, MyText will now contain "Hello World".<br />
<br />
String variables can be referenced using the syntax [&variablename]<br />
<br />
=== Call API (--@) ===<br />
<br />
ScriptCards can use a Call API instruction to execute other API commands. The Tag contains the API 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 API command is executed.<br />
<br />
Examples:<br />
<pre><br />
--@eh|list<br />
--@alter|_target|@{target|token_id} _bar|3 _amount|-[$Damage]<br />
</pre><br />
<br />
In the first example above, the command <code>!eh list</code> will be executed, calling [[EncounterHelper]]. In the second, {{fpl|1216260/ AlterBars}} is called to modify a token's Bar 3 value.<br />
<br />
'''''Note:''''' When ScriptCards (or any API script) runs other API 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).<br />
<br />
See [[API:Script Index]] for more options.<br />
<br />
=== Branch Label (--:) ===<br />
<br />
A branch label defines a line in your code that can be reached by one of the branching instructions (<nowiki>--^</nowiki>, <nowiki>--></nowiki>, or <nowiki>--?</nowiki>). The Tag serves as the label name, and must be unique on the card.<br />
<br />
The vertical bar (|) separator must be present, but the content portion of the line is unused and can be treated as a comment.<br />
<br />
Examples:<br />
<pre><br />
--:MyLoop|<br />
--:CriticalHit|Will jump here if we roll a critical hit!<br />
</pre><br />
<br />
''A Branch Label line does not produce an output line on the card.''<br />
<br />
=== Branch (--^) === <br />
<br />
A Branch line 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.<br />
<br />
Examples:<br />
<pre><br />
--^MyLoop|Jumps to MyLoop<br />
--^SkipCrit|We didn't crit, so skip the Crit code<br />
</pre><br />
<br />
''A Branch line does not produce an output line on the card.''<br />
<br />
=== Call Procedure (-->) ===<br />
<br />
Similar to a branch, a Call Procedure (sometimes knows 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 (<nowiki>--<</nowiki>) 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 (;).<br />
<br />
Examples:<br />
<pre><br />
-->FixFormat|#3333FF;#999999<br />
</pre><br />
<br />
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%].<br />
<br />
=== Return (--<) ===<br />
<br />
A return instruction marks the end of a Gosub procedure. 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.<br />
<br />
Examples:<br />
<pre><br />
--<|<br />
--<|End of MySub<br />
</pre><br />
<br />
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.<br />
<br />
=== Conditional Statement (--?) ===<br />
<br />
A conditional statement contains some equation in the Tag that will be evaluated. '''''If any part of the comparison can/does contain a space, it needs to be surrounded by double quotes'''''<br />
<br />
Based on the true/false result of the evaluation, one of two execution paths will be taken. These execution paths are detailed in the content section of the statement. The "if true" path is specified first (directly after the vertical bar), and the "if false" path is specified after it, also separated by a vertical bar.<br />
<br />
Example:<br />
<pre><br />
--?[$AttackRoll.Total] -ge [$TargetAC]|Hit|Miss<br />
</pre><br />
<br />
'''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.'''<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Branch Format !! Meaning<br />
|-<br />
| Label || If just a label is specified, execution will branch to that label when the comparison is matched.<br />
|-<br />
| >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 <br />
|-<br />
| =VariableName || The roll variable "VariableName" will be assigned the value following a semicolon (ex: --?1 -eq 1|=Roll;1d20)<br />
|-<br />
| &VariableName || The string variable "VariableName" will be assigned the value following a semicolon (ex: --?1 -eq 1|&Result;Hit|&Result;Miss)<br />
|-<br />
| % or %! || The current for...next loop will perform the "next" action (%) or will break out (%!) <br />
|-<br />
| [ || Code block (see below)<br />
|}<br />
<br />
Examples:<br />
<pre><br />
--?[$AttackRoll.Base] -eq 20|CriticalHit<br />
--?[$AttackRoll.Base] -eq 1|>Fumble;@{selected|dexterity_mod}<br />
--?"@{target|npc_type}" -inc "undead"|&MonsterType;Undead|&MonsterType;Not Undead<br />
--?[$Attack.Total] >= [$ArmorClass]|>Hit|>Miss<br />
</pre><br />
<br />
In the first example, if the Base value of AttackRoll is a 20 (natural 20 on the die) execution will branch to the CriticalHit label.<br />
<br />
In the second example, 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%].<br />
<br />
The third example looks for the word "undead" in the npc_type attribute of the targeted character. If it exists in the text, the MonsterType string variable will be set to "Undead", otherwise it will be set to "Not Undead". <br />
<br />
The final example would call 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.<br />
<br />
''Text that does/may contain a space should be enclosed in double quotes.''<br />
<br />
The following comparison operators are available:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Comparator !! Meaning<br />
|-<br />
| -eq || Equal To <br />
|-<br />
| -eqi || Case insensitive Equal To <br />
|-<br />
| -ne || Not Equal To <br />
|-<br />
| -nei || Case insensitive Not Equal To <br />
|-<br />
| -gt || Greater Than <br />
|-<br />
| -ge || Greater Than or Equal To <br />
|-<br />
| -lt || Less Than <br />
|-<br />
| -le || Less Than or Equal To <br />
|-<br />
| -inc || Includes (text strings). <br />
|-<br />
| -ninc || Does Not Include (text strings). <br />
|}<br />
<br />
Multi-part conditionals are supported with -and and -or as separators. For example:<br />
<br />
<pre><br />
--?[$Attack.Total] -ge @{target|npc_ac} -and [$Attack.Base] -ne 20|HitButNotCrit<br />
</pre><br />
<br />
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):<br />
<br />
true AND false OR true<br />
<br />
Will be evaluated as true. The first two (true and false) will be false, but then false OR true will be true.<br />
<br />
Conversely:<br />
<br />
true or false and false<br />
<br />
Will be false, because the first true and false will evaluate to true, and then true and false will be false.<br />
<br />
'''CODE BLOCKS'''<br />
<br />
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.<br />
<br />
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:<br />
<br />
<pre><br />
!script {{<br />
--=Roll|1d2<br />
--+Roll|[$Roll]<br />
--?[$Roll.Total] -eq 2|[<br />
--&Value|Yep!<br />
--+|We are inside the TRUE portion of the block<br />
--]|[<br />
--&Value|Nope<br />
--+|We are inside the FALSE portion of the block<br />
--]|<br />
--+After|the blocks!<br />
--+Value|[&Value]<br />
}}<br />
</pre><br />
<br />
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 --]|. <br />
<br />
At this time, blocks cannot be nested, and can only be created as part of a conditional (--[ is not a valid statement type)<br />
<br />
''A conditional statement does not produce a line of output on the card.''<br />
<br />
=== Case Statement (--c) ===<br />
<br />
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 (:). Each match condition includes a branch label that will be used if the test value matches the item. 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:<br />
<br />
<pre><br />
!script {{<br />
--#title|Case Statement Testing<br />
--=Roll|1d4<br />
--C[$Roll.Total]|1:>One;[$Roll]|2:>Two;[$Roll]|3:>Three;[$Roll]|4:>Four;[$Roll]<br />
--X|<br />
<br />
--:One| --+Value|was One ([%1%]) --<|<br />
--:Two| --+Value|was Two ([%1%]) --<|<br />
--:Three| --+Value|was Three ([%1%]) --<|<br />
--:Four| --+Value|was Four ([%1%]) --<|<br />
}}<br />
</pre><br />
<br />
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 variable as a parameter.<br />
<br />
=== Save and Load (--s and --l) ===<br />
<br />
This statement pair is used to either store (--s) or load (--l) data from persistent storage. Items stored in persistent storage remain between card rolls and between Roll20 sessions. There are two types of data that can be stored: settings and roll variables. <br />
<br />
Examples:<br />
<br />
<pre><br />
--Ssettings|GreenStyle<br />
--Srollvariables|FirstCardVars<br />
</pre><br />
<br />
In this case, the tag for the statement determines what type of item is being saved (settings or rollvariables). When saving settings, all non-default settings are written to the named setting storage value. When Roll Variables are saved, all variables that currently exist will be saved to the named storage value.<br />
<br />
Loading stored items simply requires the same command with the --l statement type:<br />
<br />
<pre><br />
--Lsettings|GreenStyle<br />
--Lrollvariables|FirstCardVars<br />
</pre><br />
<br />
When loading settings, all stored settings will be applied to the current card settings. You can override settings by changing them after the load.<br />
<br />
When loading roll variables, the saved variables will be added to (or overwrite if they have the same name) any variables on the current card. This means it is safe to create roll variables before the load statement.<br />
<br />
'''Practical Uses'''<br />
The major intended use of persistent storage is for storing card formats for use in later scripts. For example, the following script:<br />
<br />
<pre><br />
!scriptcard {{<br />
--#titlecardbackground|#22CC22<br />
--#oddrowbackground|#cceecc<br />
--#evenrowbackground|#99ee99<br />
--Ssettings|@{selected|token_name}<br />
}}<br />
</pre><br />
<br />
Would save the titlecardbackground, oddrowbackground, and evenrowbackground settings to a saved list named after the selected token's name. When creating cards for that token to run later, you could include the line:<br />
<br />
<pre><br />
--Lsettings|@{selected|token_name}<br />
</pre><br />
<br />
To load all of the settings at once. By creating these setting sets for each character, you can specify a different color scheme for each character that can then be used in cards with a single formatting line.<br />
<br />
There is a supplemental ! command added to support saved settings:<br />
<br />
<pre><br />
!sc-liststoredsettings<br />
</pre><br />
<br />
Will produce a list of all stored setting names, with buttons to list the setting values stored in each group and a button to delete groups as needed.<br />
<br />
=== Visual Effects (--v) ===<br />
<br />
The --v statement can be used to create visual effects on the tabletop. The tag portion of the statement can be either "token" or "betweentokens". The content portion of the statement contains the required parameters for the effect generation, separated by spaces. If the effect is "none", no effect will be played. If any other value that doesn't match a Roll20 effect name will result in a burst-fire effect.<br />
<br />
For "token" effects, the parameters are the token id for the token the effect happens on, followed by the effect specifier.<br />
<br />
Example:<br />
<pre><br />
--vtoken|@{selected|token_id} burst-fire<br />
</pre><br />
<br />
For "betweentoken" effects, the parameters are the source token id, the target token id, and the effect specifier.<br />
<br />
Example:<br />
<pre><br />
--vbetweentokens|@{selected|token_id} @{target|token_id} beam-magic<br />
</pre><br />
<br />
'''''Version 1.2.8+'''''<br />
<br />
An additional effect specifier, "point" is available in 1.2.8+. This specifier allows you to create a visual effect at a designated X/Y pixel coordinate. Future updates will add custom-vfx support to this option. The parameters are the X and Y coordinates and the effect descriptor. As of version 1.2.9, you can also use custom effect specifiers with Point effects:<br />
<br />
<pre><br />
--vpoint|150 200 burst-fire<br />
</pre><br />
<br />
=== Echo to Chat (--e) ===<br />
<br />
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.<br />
<br />
Example:<br />
<pre><br />
--eThe Ghost|/em hovers around @{selected|character_name}... BOO!<br />
</pre><br />
<br />
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).<br />
<br />
'''''Whispering'''''<br />
<br />
You can use the echo statement to send a whisper, but there's a trick to it. If you execute this code here:<br />
<br />
<pre><br />
--eThe Ghost|/w ExamplePlayerName Boo.<br />
</pre><br />
<br />
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.<br />
<br />
So, in conclusion, it's best to use something like this when you're sending a whisper:<br />
<br />
<pre><br />
!script {{<br />
--#hidecard|1<br />
--&sender|The Ghost<br />
--&receiver|ExamplePlayerName<br />
--&message|Boo.<br />
--e[&sender]|/w [&receiver] [&message]<br />
--eScriptCards|/w gm **Whispered from [&sender] to [&receiver]:** [&message] <br />
}}<br />
</pre><br />
<br />
This will ensure that the message appears in your chat feed as well.<br />
<br />
=== Repeating Section Access (--R) ===<br />
<br />
ScriptCards (as of v0.0.13) supports accessing repeating section rows on a character sheet with the --R statement type. <br />
<br />
There are three basic commands you can use with --R, and they are specified by the tag used:<br />
<br />
<pre><br />
--Rfind|characterid;EntryName;SectionPrefix;SearchField<br />
</pre><br />
<br />
This is the most direct way to access a repeating section row. Supplying the character ID, followed by what you are looking for (Greatsword, for example), followed by the character sheet's section prefix (repeating_attack), followed by the field to check what you are searching for (atkname) will load the matching section (if found) into the script parsers memory. For example:<br />
<br />
<pre><br />
--Rfind|@{selected|character_id};Greatsword;repeating_attack;atkname<br />
</pre><br />
<br />
Will look at the character's "repeating_attack" section for an entry with an atkname value equal to "Greatsword". Similarly:<br />
<br />
<pre><br />
--Rfind|@{selected|character_id};Bite;repeating_npcaction;name<br />
</pre><br />
<br />
Will look for a "Bite" action on an NPC's action list.<br />
<br />
<pre><br />
--Rfirst|characterid;section prefix<br />
</pre><br />
<br />
This form of the --R command will look at all of the entries in the specified repeating section and load the first one into memory:<br />
<br />
<pre><br />
--Rfirst|@{selected|character_id};repeating_attack<br />
</pre><br />
<br />
Would load the character's first "repeating_attack" row into memory.<br />
<br />
<pre><br />
--Rnext|<br />
</pre><br />
<br />
No parameters are required for --Rnext, which loads the next entry in the list that was obtained with "first" into memory.<br />
<br />
However a row is obtained, it will be parsed to replace any attribute references (ie, @{level}) with the corresponding character attribute.<br />
<br />
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".<br />
<br />
You can reference repeating attribute data using the syntax [*R:attributename] syntax (similar to referencing standard character attributes).<br />
<br />
Here are some examples:<br />
<br />
Display the details of the "Greatsword" PC attack:<br />
<br />
<pre><br />
!script {{<br />
--Rfind|@{selected|character_id};Greatsword;repeating_attack;atkname<br />
--+Attack Name|[*R:atkname]<br />
--+Base Damage|[*R:dmgbase]<br />
}}<br />
</pre><br />
<br />
[[File:Scriptcards repeating greatsword.png|Repeating Greatsword Attack]]<br />
<br />
List all of the actions an NPC can take (just actions, not legendary, etc.)<br />
<br />
<pre><br />
!script {{<br />
--#title|NPC Actions<br />
--#leftsub|@{selected|token_name}<br />
--Rfirst|@{selected|character_id};repeating_npcaction<br />
--:DisplayLoop|<br />
--?"[*R:name]" -eq NoRepeatingAttributeLoaded|Done<br />
--+Action:|[*R:name] [*R:attack_damage] [*R:attack_damagetype]<br />
--?"[*R:attack_damage2]" -eq ""|NoSecondaryDamage<br />
--+ |[*R:attack_damage2] [*R:attack_damagetype2]<br />
--:NoSecondaryDamage|<br />
--Rnext|<br />
-->DisplayLoop| <br />
--:Done|<br />
}}<br />
</pre><br />
<br />
[[File:Scriptcards repeating npcactions.png]]<br />
<br />
In the script above, we get the "first" repeating_npcaction and display information about it. We then execute "next" and repeat until we run into "NoRepeatingAttributeLoaded".<br />
<br />
'''''Special debugging command: dump'''''<br />
<pre><br />
--Rdump|<br />
</pre><br />
<br />
The "dump" command will list all of the attributes ScriptCards knows about for the currently loaded repeating row to the API Console Log.<br />
<br />
=== Assign Variable to Built-In Function (--~) ===<br />
<br />
ScriptCards has the ability to run a function built into the API script and return the results to a variable. Some functions return roll variables, while others return strings. See the function table below for details. The format is:<br />
<br />
--~VariableName|function;param1;param2;param3;...<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Function Name !! Parameters !! Description<br />
|-<br />
| distance || token_A_ID;token_B_ID || Calculate the Chebyshev distance in grid units between two tokens. This is the measurement scheme D&D 4E/5E use for diagonal distance measurement<br />
|-<br />
| euclideandistance || token_A_ID;token_B_ID || Calculate the Euclidean distance between two tokens. This is essentially the Pythagorean theorem in action. Returns the result in grid units.<br />
|-<br />
| euclideanpixel || token_A_ID;token_B_ID || Calculate the Euclidean distance between two tokens and returns the result is pixels instead of grid units. <br />
|-<br />
| euclideanlong || token_A_ID;token_B_ID || 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 is calculated instead of before. More accurate over long distances. <br />
|-<br />
| manhattandistance || token_A_ID;token_B_ID || Also called "taxicabdistance" (which is an acceptable function name), this measures to how-many-over, how-many-up/down distance, disallowing diagonal movement.<br />
|-<br />
| getselected || none || 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 the first selected token, VariableName2 the second, etc.<br />
|}<br />
<br />
'''''Functions with Sub Functions'''''<br />
<br />
Most ScriptCards functions are grouped into set as sub functions. The table below lists the major functions and their sub functions.<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Function Name !! Sub Function !! Parameters !! Return Type !! Description<br />
|-<br />
| array || define || arrayname;value1;value2;... || none || Creates an array called "arrayname" and adds value1, value2, etc. to the array<br />
|-<br />
| array || sort || arrayname || none || Sorts the specified array in place in ascending order<br />
|-<br />
| array || add || arrayname;value1;value2;... || none || Adds value1, value2, ... to the existing array "arrayname"<br />
|-<br />
| array || remove || arrayname;value1;value2;... || none || Removes value1, value2, ... from the existing array "arrayname". Resets the array index to 0.<br />
|-<br />
| array || replace || arrayname;currentvalue;newvalue || none || Replaces all occurrences of "currentvalue" in "arayname" with "newvalue"<br />
|-<br />
| array || setatindex || arrayname;index;newvalue || none || Replaces the array item at index "index" with "newvalue"<br />
|-<br />
| array || getindex || arrayname || stringVariable || Retrieves the current index in "arrayname" and stores it in the supplied string variable<br />
|-<br />
| array || setindex || arrayname;newindex || none || Sets the current index in array "arrayname" to "newindex"<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| array || removeat || arrayname;indexposition || none || Removes the item at index "indexposition" from "arrayname". Resets the current array index to 0.<br />
|-<br />
| array || indexof || arrayname;searchvalue || stringVariable || Searches the array "arrayname" for and item with the value of "searchvalue" and, if found, returns the index of the first matching value or "ArrayError" if not found<br />
|-<br />
| array || getlength || arrayname || stringVariable || Returns the number of items in array "arrayname"<br />
|-<br />
| array || pagetokens || arrayname;tokenid;(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. 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.)<br />
|-<br />
| 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.<br />
|-<br />
| array || stringify || arrayname || stringVariable || Returns all of the items in "arrayname" as a string separated by semicolons (;)<br />
|-<br />
| array || fromstring || arrayname || delimiter;string || Creates an array from "string", splitting "string" on "delimiter" to separate the items<br />
|-<br />
| array || statusmarkers|| arrayname;tokenid || none|| Creates an array (arrayname) of the active statusmarkers (sometimes called Token Markers) for the specified tokenid<br />
|-<br />
| math || angle || math;angle;tokenid;tokenid|| rollVariable || Calculates the angle between two tokens and returns the value in degrees<br />
|-<br />
| math || ceil || math;ceil;value || rollVariable || Rounds '''value''' up to the next integer, dropping any decimal portion of the number<br />
|-<br />
| math || clamp || math;clamp;value;lowerBound;upperBound || rollVariable || Returns '''value''', but restricted to the range of '''loweBound''' and '''upperBound'''.<br />
|-<br />
| math || floor || math;floor;value || rollVariable || Rounds '''value''' down, dropping any decimal portion of the number<br />
|-<br />
| math || max || math;max;valueA;valueB || rollVariable || Returns the larger of '''valueA''' vs '''valueB'''<br />
|-<br />
| math || min || math;min;valueA;valueB || rollVariable || Returns the smaller of '''valueA''' vs '''valueB'''<br />
|-<br />
| math || round || math;round;value || rollVariable || Rounds '''value''' to the nearest integer<br />
|-<br />
| string || length || string;length;stringValue || rollVariable || Returns the length of '''stringValue''' in characters<br />
|-<br />
| string || before || string;before;searchText;stringValue || stringVariable || Searches '''stringValue''' for '''searchText''' and returns the portion of '''stringValue''' prior to that text<br />
|-<br />
| string || after || string;after;searchText;stringValue || stringVariable || Searches '''stringValue''' for '''searchText''' and returns the portion of '''stringValue''' after that text<br />
|-<br />
| string || left || string;left;count;stringValue || stringVariable || Returns the leftmost '''count''' characters of '''stringValue'''<br />
|-<br />
| string || right || string;right;count;stringValue || stringVariable || Returns the rightmost '''count''' characters of '''stringValue'''<br />
|-<br />
| string || replace || string;replace;searchText;replaceText;stringValue || stringVariable || Replaces '''searchText''' in '''stringValue''' with '''replaceText''' and returns the resulting string<br />
|-<br />
| string || replaceall || string;replace;searchText;replaceText;stringValue || stringVariable || Replaces all intances of '''searchText''' in '''stringValue''' with '''replaceText''' and returns the resulting string '''''Requires 1.2.9+'''''<br />
|-<br />
| string || trim || string;trim;stringValue || stringVariable || Removes leading and trailing spaces from stringValue and returns the result. <br />
|-<br />
| string || substring || string;substring;start;count;stringValue || stringVariable || Returns '''count''' characters starting at '''start''' from '''stringValue'''<br />
|-<br />
| 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.<br />
|-<br />
| string || tolowercase || string;tolowercase;stringValue || stringVariable || Converts the passed string to lower case and assigns to the passed variable name. <br />
|-<br />
| string || touppercase || string || stringVariable || Converts the passed string to upper case and assigns to the passed variable name. <br />
|-<br />
| 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. <br />
|-<br />
| 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.<br />
|-<br />
| 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'''.<br />
|-<br />
| turnorder || clear || none || none || Clears all entries from the {{Turn Tracker}}/Initiative<br />
|-<br />
| turnorder || addtoken || tokenid;trackervalue || none || Adds the token represented by "tokenid" to the initiative tracker with an initiavie value of "trackervalue"<br />
|-<br />
| turnorder || replacetoken || tokenid;trackervalue || none || Replaces the token represented by "tokenid" in the initiative tracker with an initiavie value of "trackervalue". Will add the token if it doesn't exist in the tracker.<br />
|-<br />
| turnorder || removetoken || tokenid || none || Removes the token represented by "tokenid" from the initiative tracker if it exists<br />
|-<br />
| turnorder || addcustom || textlabel;trackervalue || none || Add a custom text entry to the {{Turn Tracker}}/Initiative named "textlabel" with an initiative value of "trackervalue"<br />
|-<br />
| system || date || getdatetime || stringVariable || Returns the date time in the active timezone (see settings) <br />
|-<br />
| system || date || getdate || stringVariable || Returns the date in the active timezone (see settings) <br />
|-<br />
| system || date || gettime || stringVariable || Returns the time in the active timezone (see settings)<br />
|-<br />
| system || dumpvariables || "rolls", "string", or "array" || none || Dumps all of the defined variables of the indicated type to the console log<br />
|-<br />
| system || findability || system;findability;charactername;abilityname || stringVariable || Returns the object ID of the ability on the indicated character or "AbilityNotFound"<br />
|-<br />
|}<br />
<br />
Examples:<br />
<br />
<pre><br />
--~HowFarAway|distance;@{selected|token_id};@{target|token_id}<br />
</pre><br />
<br />
Returns the distance (Chebyshev) between the selected and target tokens and stores it in "HowFarAway".<br />
<br />
<pre><br />
--SelectedDudes|getselected<br />
</pre><br />
<br />
If 5 tokens were selected, 6 variables would be created: SelectedDudesCount (with a value of 5), SelectedDudes1, SelectedDudes2, SelectedDudes3, SelectedDudes4, SelectedDudes5.<br />
<br />
=== Information Request (--i) ===<br />
<br />
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.<br />
<br />
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.<br />
<br />
After the user has clicked the button and responded to the requests, ScriptCards will resume processing the script from where it left off.<br />
<br />
Here is an example “i” line:<br />
<br />
<pre><br />
--IScriptCards needs additional information to continue;Click to select a target and provide information|t;MyNewTarget;Missile1Target||q;MyNameIs;What is your name?<br />
</pre><br />
<br />
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.<br />
<br />
Supported information request types are “t” for target token, and “q” for query.<br />
<br />
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).<br />
<br />
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:<br />
<br />
<pre><br />
q;UserName;What is your name?|Fred|Bob|Sally|Nancy<br />
</pre><br />
<br />
Would have a dropdown menu with four choices.<br />
<br />
== Inline Formatting ==<br />
<br />
Inline formatting is processed on Direct Output lines only (--+ lines) and the following inline format markup is available:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Formatting Tags !! Description<br />
|-<br />
| [b]..[/b] || Bold the text between the markers <br />
|-<br />
| [i]..[/i] || Italicize the text between the markers <br />
|-<br />
| [u]..[/u] || Underline the text between the markers <br />
|-<br />
| [s]..[/s] || Strike-Thru the text between the markers <br />
|-<br />
| [c]..[/c] || Center alignment <br />
|-<br />
| [l]..[/l] || Left alignment <br />
|-<br />
| [r]..[/r] || Right alignment <br />
|-<br />
| [j]..[/j] || Full justification alignment <br />
|-<br />
| [#xxx]..[/#] or [#xxxxxx]..[/#] || Use a 3 or 6 digit hex code to colorize the text between the markers <br />
|-<br />
| [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, <code>[img width=128 height=128]</code> )<br />
|-<br />
| [button]caption::action[/button] || Create a button with the label "caption" that performs the action defined by "action". <br />
|-<br />
| [t] || Converted to HTML table tag. Text after the "t" will be included inside the tag (width, border, etc)<br />
|-<br />
| [/t] || Converted to HTML close table tag.<br />
|-<br />
| [tr] || Converted to HTML table row tag. Text after the "tr" will be included inside the tag<br />
|-<br />
| [/tr] || Converted to HTML close table row tag.<br />
|-<br />
| [td] || Converted to HTML table cell tag. Text after the "tr" will be included inside the tag<br />
|-<br />
| [/td] || Converted to HTML close table cell tag.<br />
|}<br />
<br />
== Variables ==<br />
<br />
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. While it is possible to assign both a string and a roll variable the same name, doing so will likely result in confusion when looking at the script later, so it is not recommended.<br />
<br />
String Variables are assigned with the --& statement and are referenced using [&variableName] notation.<br />
<br />
Roll Variables are assigned with the --= statement, and the assignment value is always processed by the ScriptCards Roll Processor (resolves dice rolls, etc.)<br />
<br />
There are a handful of variables assigned automatically when a ScriptCard is executed. These are all string variables, and are:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Variable !! Value<br />
|-<br />
| SendingPlayerID || Contains the object ID of the player that sent the macro<br />
|-<br />
| SendingPlayerName || Contains the display name of the player<br />
|-<br />
| SendingPlayerColor || Contains the color code associated with the player<br />
|-<br />
| SendingPlayerSpeakingAs || The contents of the "Speaking As" dropdown window<br />
|-<br />
| SendingPlayerIsGM || Contains 1 if the player is a GM, and 0 if the player is NOT a GM<br />
|}<br />
<br />
== Arrays ==<br />
<br />
Arrays are a special type of variable, and are managed by the function (<nowiki>--~</nowiki> command). All of the array function commands follow the same pattern:<br />
<br />
<pre>--~variableName|array;subcommand;arrayname;param1;param2;param3;...</pre><br />
<br />
Not all array commands return anything to "variableName". The function table above will specify the return type of the command if any.<br />
<br />
There are a couple of different ways to create an array:<br />
<br />
The '''define''' array subcommand creates (or recreates) an array and assigns it values - one for each included parameter after the array name. For example:<br />
<br />
<pre>--~|array;define;Fruits;mango;peach;strawberry;apricot;banana;apple</pre><br />
<br />
will create an array called '''Fruits''' with 6 elements in the order listed in the command (mango, peach, etc.)<br />
<br />
You can also use two other subcommands to create arrays based on tokens:<br />
<br />
<pre>--~Count|array;pagetokens;Everybondy;@{selected|token_id}</pre><br />
<br />
and<br />
<br />
<pre>--~Count|array;selectedtokens;Selected</pre><br />
<br />
In both cases, arrays of tokens will be created, and a string variable called "Count" will be set to the number of tokens in the array. The '''pagetokens''' command returns (by default) all of the tokens on the page that contains the token passed as the parameter after the array name. You can filter the tokens that "pagetokens" includes in the array by appending an optional parameter describing the type of token you are looking for:<br />
<br />
<pre>--~Count|array;pagetokens;Everybondy;@{selected|token_id};npc</pre><br />
<br />
Will return only tokens on the page that represent characters that do not have a ''controlledby'' parameter set. The available options are "all" (default), "char", "graphic", "pc", and "npc".<br />
<br />
The '''selectedtokens''' command returns an array with all of the tokens that were selected when the script was called.<br />
<br />
You can also use an arbitrary string to create an array, specifying a delimiter with the '''fromstring''' command:<br />
<br />
<pre><br />
--&names|Fred<br />
--&names|+,Sally<br />
--&names|+,Ted<br />
--&names|+,Joyce<br />
--~|array;fromstring;,;[&names]<br />
</pre><br />
<br />
The above example builds a comma-separated string and then uses "fromstring" to create an array with 4 elements from it, specifying the comma as the delimiter.<br />
<br />
Finally, you can use the '''statusmarkers''' command to create an array with one entry for each active status marker on a specified token:<br />
<br />
<pre>--~|array;statusmarkers;Conditions;@{selected|token_id}</pre><br />
<br />
will create an array with one entry for each status active on the selected token. The array elements will be the internal name of the status (if you are using custom status marker packs, the names will be specified in the marker pack).<br />
<br />
'''Traversing Arrays'''<br />
<br />
Each array keeps track of an internal index position (starting at 0). Several commands let you manage this index:<br />
<br />
*'''getindex''' returns the current index value<br />
*'''setindex''' sets the index to the specified location in the array<br />
*'''getlength''' returns the number of elements in the array<br />
*'''indexof''' returns the index location of the specified element<br />
<br />
Other commands let you retrieve values from the array:<br />
<br />
*'''getfirst''' sets the index to 0 and returns the value at that position<br />
*'''getnext''' advances the index by 1 and returns the new current value<br />
*'''getprevious''' reduces the index by 1 and returns the new current value<br />
*'''getlast''' sets the index to the last elements in the array and returns the new current value<br />
<br />
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.<br />
<br />
'''Manipulating Array Elements'''<br />
<br />
Several array commands deal with inserting, removing, and modifying elements:<br />
<br />
*'''add''' works just like define, except that it takes an existing array and adds elements to it based on the passed parameters<br />
*'''remove''' looks for items matching each passed parameter and removes them from the indicated array if they exist<br />
*'''removeat''' allows you to specify an index location in the array and remove the element at that position<br />
*'''replace''' searches an array for a value and replaces all occurrences of it with a new value (if found)<br />
*'''sort''' sorts the elements in the array in ascending order<br />
*'''strinfigy''' returns a string variable that includes each array element separated by semicolons (;) <br />
<br />
'''Referencing Array Elements'''<br />
<br />
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.<br />
<br />
<pre><br />
!script {{<br />
--~dummy|array;pagetokens;myarray;@{selected|token_id}<br />
--~count|array;getcount;myarray<br />
--+Total:|There are [&count] graphical objects on the page<br />
--~testvar|array;getfirst;myarray<br />
--:loop|<br />
--+Value|[*[&testvar]:character_name]<br />
--~testvar|array;getnext;myarray<br />
--?[&testvar] -ne ArrayError|loop<br />
--+Loop1|Is Done!<br />
}}<br />
</pre><br />
<br />
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:<br />
<br />
<pre><br />
!script {{<br />
--~dummy|array;pagetokens;myarray;@{selected|token_id}<br />
--~count|array;getcount;myarray<br />
--+Total:|There are [&count] graphical objects on the page<br />
--%loopCounter|1;[&count]<br />
--+Value|[*[@myarray([&loopCounter])]:character_name]<br />
--%|<br />
--+Loop|Is Done!<br />
}}<br />
</pre><br />
<br />
This line : <nowiki>--+Value|[*[@myarray([&loopCounter])]:character_name]</nowiki> uses [@arrayName(index)] format (inside a [*characterid:attribute] syntax) to perform the same task as running through the loop with the index.<br />
<br />
(Note: Additional examples are on the way...)<br />
<br />
== For...Next Loops ==<br />
<br />
For...Next loops in ScriptCards are supported with the with the --% statement type. A loop is defined by starting off with:<br />
<br />
<pre><br />
--%LoopCounter|<start>;<end>;[step]<br />
</pre><br />
<br />
The start and end values are required, while the step parameter is optional. If the step is omitted, it will be assumed to be 1. A string variable named after the line tag ("LoopCounter" in the case above) will be created and will hold the current iteration value for the loop. Here is a real example:<br />
<br />
<pre><br />
--%LoopCounter|1;10;1<br />
</pre><br />
<br />
This will begin a loop identified by "LoopCounter" that will start at 1, increasing by 1 each iteration (the step) until it has completed 10 executions.<br />
<br />
The "next" statement is simply <code>--%|</code>, with no tag or parameters. This indicates to ScriptCards that it should increment the counter and go back to the beginning of the loop. Extending the example above:<br />
<br />
<pre><br />
!script {{<br />
--%LoopCounter|1;10;1<br />
--=Roll|1d20<br />
--+Loop|Counter is [&LoopCounter], roll was [$Roll]<br />
--%|<br />
}}<br />
</pre><br />
<br />
The <code>--%!|</code> sequence will break out of the loop, no matter how many iterations are remaining.<br />
<br />
The % and %! character sequences can also be used as part of a 1.2.1+ non-branching conditional to continue or break the loop:<br />
<br />
<pre><br />
--?"X[&RollInto]X" -eq "XX"|%<br />
</pre><br />
<br />
In this example, if the string variable RollInfo is empty, the loop will return to the top and continue with the next iteration, while:<br />
<br />
<pre><br />
--?"X[&RollInto]X" -eq "XX"|%!<br />
</pre><br />
<br />
Would cause the whole loop to end if the condition were true.<br />
<br />
== Referencing ==<br />
<br />
=== Roll Variables===<br />
<br />
Roll Variables can be referenced from the content portion of any line type, and from the tag portion of conditional statements. The referenced value is replaced when the line is executed.<br />
<br />
There are several modifiers that can be used to reference parts of a roll:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Modifier !! Meaning<br />
|-<br />
| No modifier || In a Direct Output Line (<nowiki>--+</nowiki>), GM Output Line (<nowiki>--*</nowiki>), or String Assignement (<nowiki>--&</nowiki>), 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<br />
|-<br />
| .Total || The end result of the roll equation. Formatting rules for "No Modifier" apply based on line type. <br />
|-<br />
| .Raw || The total value of the roll variable without any formatting, no matter what kind of line the reference is used in.<br />
|-<br />
| .Base || The cumulative result of any dice rolled in the Roll Text (Numeric modifiers are not included) <br />
|-<br />
| .Ones || The number of dice in the roll that came up as 1s <br />
|-<br />
| .Aces || The number of dice in the roll that came up as the maximum number on the die <br />
|-<br />
| .Odds || The number of dice in the roll that came up with an odd number <br />
|-<br />
| .Evens || The number of dice in the roll that came up with an even number <br />
|-<br />
| .RollText || The raw text of the roll that was use to generate the results <br />
|-<br />
| .Text || A text representation of the results of the roll, including the numbers rolled for each die <br />
|-<br />
| .tableEntryText || The text portion of the result of a table roll<br />
|-<br />
| .tableEntryImgURL || The image source portion of the result of a table roll<br />
|-<br />
| .tableEntryValue || If the tableEntryText is purely numeric, will contain the numeric value<br />
|}<br />
<br />
=== String Variables ===<br />
<br />
To reference a string variable, use the notation [&variablename]. String variables can be referenced in direct output, roll variable assignment, and string variable assignment statements.<br />
<br />
=== Character/Token Attributes ===<br />
<br />
A character or token attribute can be referenced from content portion of any type of line and is substituted when the line is executed. The general format for referencing a character attribute is [*ID:attribute]. ID can be a token ID or a character ID (these start with a dash). Additionally if you have specified a sourceToken or targetToken, you can substitute "S" or "T" for the ID (for example [*S:npc_type] will retrieve the npc_type attribute from the source token.<br />
<br />
By default, all attribute references will be pulled from the '''''character''''' object that the ID represents (either directly or by being a Token ID that represents a character).<br />
<br />
Keep in mind, that if you want to access the "max" of a character attribute (for example, the max hit points), then you cannot trust the name that your roll20 character sheet shows you when you hover your mouse over the max hit points. For example, this reference will not work: [*S:hp_max]. Instead, you need to use this reference: [*S:hp^].<br />
<br />
If your ID refers to a token, token attributes can be accessed by preceding the attribute name with "t-", for example [*S:t-aura1_radius]. Supported token attributes are:<br />
<br />
{|<br />
| t-name || t-id || t-statusmarkers || t-bar1_value<br />
|-<br />
| t-bar1_max || t-bar2_value || t-bar2_max || t-bar3_value<br />
|-<br />
| t-bar3_max || t-top || t-left || t-width<br />
|-<br />
| t-height || t-rotation || t-layer || t-aura1_radius<br />
|-<br />
| t-aura1_color || t-aura2_radius || t-aura2_color || t-aura1_square<br />
|-<br />
| t-aura2_square || t-tint_color || t-light_radius || t-light_dimradius<br />
|-<br />
| t-light_angle || t-light_losangle || t-light_multiplier || t-light_otherplayers<br />
|-<br />
| t-light_hassight || t-flipv || t-fliph || t-controlledby<br />
|-<br />
| t-_cardid || t-_pageid || t-imgsrc || t-bar1_link<br />
|-<br />
| t-bar2_link || t-bar3_link || t-represents || t-layer<br />
|-<br />
| t-isdrawing || t-name || t-gmnotes || t-showname<br />
|-<br />
| t-showplayers_name || t-showplayers_bar1 || t-showplayers_bar2 || t-showplayers_bar3<br />
|-<br />
| t-showplayers_aura1 || t-showplayers_aura2 || t-playersedit_name || t-playersedit_bar1<br />
|-<br />
| t-playersedit_bar2 || t-playersedit_bar3 || t-playersedit_aura1 || t-playersedit_aura2<br />
|-<br />
| t-lastmove || t-adv_fow_view_distance || t-has_bright_light_vision || t-has_night_vision<br />
|-<br />
| t-night_vision_distance || t-emits_bright_light || t-bright_light_distance || t-emits_low_light<br />
|-<br />
| t-low_light_distance || t-has_limit_field_of_vision || t-limit_field_of_vision_center || t-limit_field_of_vision_total<br />
|-<br />
| t-has_limit_field_of_night_vision || t-limit_field_of_night_vision_center || t-limit_field_of_night_vision_total || t-has_directional_bright_light<br />
|-<br />
| t-directional_bright_light_center || t-directional_bright_light_total || t-has_directional_dim_light || t-directional_dim_light_center<br />
|-<br />
| t-directional_dim_light_total || t-lightColor || || |<br />
|}<br />
<br />
'''''It is important to note that some attributes names on tokens have corresponding attribute names on characters, which represent different values. For example, [*T:id] returns the character ID, while [*T:t-id] returns the token ID.'''''<br />
<br />
=== Subroutine Parameters ===<br />
<br />
When using a gosub statement (-->) or a conditional marked as a gosub (prefixing the label with a > character), you can pass any number of parameters separated by semicolons (;) that the code in the subroutine can utilize.<br />
<br />
Subroutine parameters are numbered starting at 1, and are accessed by using the notation [%number%], so the first parameter is [%1%], the second is [%2%], etc.<br />
<br />
Parameter substitution happens on all line types, and happens prior to character attribute references or roll variable substitution.<br />
<br />
=== Campaign Attribute ===<br />
You can retrieve properties of the API's Campaign object with the [*C:attributename] syntax. For example, [*C:playerpageid] will retrieve the current player ribbon page from the Campaign object.<br />
<br />
=== Page Attributes ===<br />
If you have set the '''activepage''' parameter, you can retrieve page-related properties with the [*P:attributename] syntax, including the page's UDL parameters.<br />
<br />
=== Repeating Section Values ===<br />
<br />
You can reference repeating attribute data using the syntax [*R:attributename] syntax (similar to referencing standard character attributes). The currently active repeating row information will be used to retrieve attribute values. You can also retrieve the full attribute name for a repeating row attribute by using the [*R>attributename] notation. This is useful to pass to things like chatsetattr.<br />
<br />
=== Array Elements ===<br />
After an array has been declared, the elements can be referenced with [@arrayName(index)]. Array indices start at 0.<br />
<br />
== Deferred Resolution for Meta Scripts ==<br />
<br />
As of 1.2.9, ScriptCards supports a deferral character for use when calling another API script with via the --@ statement, to defer processing of meta script references so they get processed prior to the sub-API call insted of prior to ScriptCards execution. To defer this processing for meta script (SelectManager, Fetch) by inserting a deferral character into the meta call. For example, if I want to have ScriptCards call TokenMod as if the token for "Quej Gr'stra" (yes, I let Roll20 name my test NPCs) I could use something like this:<br />
<br />
--@token-mod|{^& select Quej Gr'stra} _on showname<br />
<br />
The "^" in between { and & will prevent SelectManager from seeing the call when the ScriptCard script is processed, but the --@ statement will remove the deferral character so the command that will be sent by ScriptCards is:<br />
<br />
!token-mod {& select Quej Gr'stra} --on showname<br />
<br />
With the deferral character removed, SelectManager will see the {& select ...} and do its magic.<br />
<br />
While the default deferral character is "^", the deferral character is a setting that can be changed:<br />
<br />
--#deferralcharacter|%<br />
<br />
Will make % the deferral character for future --@ statements in the running script.<br />
<br />
There are currently three supported Meta script structures: {^&...} for SelectManager, @^(...) and *^(...) for fetch, where the ^ in the structures here represents the placement of the deferral character.<br />
<br />
== Arrays ==<br />
<br />
Arrays are a new data type introduced in version 1.1.12 of ScriptCards, and are manipulated with associated function (--~) commands.<br />
<br />
* Arrays are a lists of strings. Items in an array cannot contain the semi-colon (;) character, as that is used to separate parameters in the function code that deals with arrays.<br />
* Arrays are accessed via the --~ script command. In some cases, the value of the tag (variable name) for array commands is not used, and can be a dummy value or simply omitted. I have omitted them in the statements below.<br />
* All commands that DO return a value return string values, even if the content is numeric.<br />
* If a command returns a value and there is some sort of reason that it isn't an array value, you will get "ArrayError" in the return value. This can happen if you reach the end of an array while stepping through it, for example, so checking for "ArrayError" can serve as the end condition for a loop.<br />
* Each array keeps track of its current index, allowing you to step forward and backwards through arrays.<br />
* Any number of arrays can be defined.<br />
* Unlike string variables and roll variables, array variables cannot (currently) be referenced directly. It is necessary to use the function (--~) syntax to manipulate arrays and get values from them as strings for use in other parts of your script.<br />
<br />
<br />
== Reentrant Scripts ==<br />
<br />
Reentrant scripts allow you to create buttons in your script code that will re-execute the script at a given label within the code. If you set the reentrant setting (--#reentrant|somevalue) to a non-zero value, your setting and variable information will be preserved between executions. Reentrant script can be used to present menus or choices and then continue acting.<br />
<br />
Reentrant buttons are created with the [rbutton]Caption::ReentryLabel;Parameter[/rbutton] construct. The caption will be displayed on the generated button. ReentryLabel is the name of a label in your script that the button will jump to when clicked, and Parameter will be passed in as a string value called "reentryval".<br />
<br />
Example:<br />
<pre><br />
!script {{<br />
--#reentrant|testing<br />
--=Roll|1d20<br />
--+Roll|[$Roll]<br />
--&String|That was a [$Roll.Raw]!<br />
--~x|array;define;MyArray;Apple;Banana;Orange<br />
--+Try it|[rbutton]Hello!::EXEC_PC_SPELL;9[/rbutton]<br />
--X|<br />
<br />
--:EXEC_PC_SPELL|<br />
--+ReentryVal|[&reentryval]<br />
--+The value of Roll is|[$Roll]<br />
--+Value of String|[&String]<br />
--+Array|[@MyArray(0)]<br />
--X|<br />
}}<br />
</pre><br />
<br />
This script sets up some variables and then displays a button labeled "Hello!". If the user clicks the button, the script will be re-entered starting at the "EXEC_PC_SPELL", which will display the content of the variables from the original execution.<br />
<br />
'''''Note: This section needs to be expanded upon'''''<br />
<br />
== Procedure Libraries ==<br />
<br />
You can now create handouts in your game in Roll 20 with the name format "ScriptCards Library NAME", where name is a name you assign to the library. Library names are case sensitive. It is my hope that the more proficient ScriptCards scripters out there will provide procedure libraries (or procedures that can be included in libraries) for others to use to make their scripting life easier. Be they specific to a game system, or to a type of activity, I think a robust set of libraries that GMs could use to enhance their scripting capabilities would be very valuable to the community. Should such things begin to emerge, I’ll create a portion of the ScriptCards Wiki page to house them.<br />
<br />
To include one or more libraries in a script, use the +++libname+++ directive (does not need a -- line associated with it). Multiple library names can be specified by separating them with semicolons (i.e., +++General;dnd5elib;Colorize+++ would include three libraries (General, dnd5elib, and Colorize).<br />
<br />
Included libraries are separated from the main script code by the automatic inclusion of "--X|" before the first library is appended to the script, and all libraries are loaded at the end of the script before script processing takes place.<br />
<br />
Procedures and labels in libraries can be used just as if they were included in the body of your script. Note that this DOES mean that you could, technically, jump into a library with a direct branch (--^) or direct branch conditional, but I recommend using libraries to store reusable procedures.<br />
The Notes section of the library handout stores the library code, and is written just like any other ScriptCards code except:<br />
<br />
* They cannot use roll queries (?{Some Prompt:}) to get information from the user at execution time.<br />
* They cannot use @{} notation to access character and token information.<br />
<br />
Both of these limitation stem from the fact that Procedure Libraries are not processed by the chat server, which is what handles these items.<br />
<br />
Here is an example of handling damage modifications (resistance, vulnerability, and immunity) in D&D 5E with a library:<br />
<br />
<pre><br />
!script {{<br />
+++dnd5elib+++<br />
--#|Damage Modifiers Test<br />
--#targettoken|@{target|token_id}<br />
-->Lib5E_CheckDamageModifiers|ResistType;fire<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] fire damage<br />
<br />
-->Lib5E_CheckDamageModifiers|ResistType;cold<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] cold damage<br />
<br />
-->Lib5E_CheckDamageModifiers|ResistType;poison<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] poison damage<br />
<br />
-->Lib5E_CheckDamageModifiers|ResistType;acid<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] acid damage<br />
<br />
--X|<br />
}}<br />
</pre><br />
<br />
Library content (In a handout called “ScriptCards Library dnd5elib” NOTE: Paste into Notepad first and then paste into the handout in Roll20 to avoid bringing over HTML formatting from the web site):<br />
<br />
<pre><br />
--/|ScriptCards Library: dnd5elib version 0.0.1<br />
--/|Provides various utility procedures for D&D 5E games<br />
<br />
--/|Lib5E_CheckDamageModifiers handle damage resistance, vulnerability, and immunity. <br />
--/|Pass a string variable to be filled with a string to be appended to a dice roll and the damage type <br />
<br />
--:Lib5E_CheckDamageModifiers|damageVariableName;damageType<br />
--&[%1%]|<br />
--?"[*T:npc_vulnerabilities]" -inc "[%2%]"|>_Lib5E_IsVulnerable;[%1%]<br />
--?"[*T:npc_resistances]" -inc "[%2%]"|>_Lib5E_IsResistant;[%1%]<br />
--?"[*T:npc_immunities]" -inc "[%2%]"|>_Lib5E_IsImmune;[%1%]<br />
--<|<br />
<br />
--:_Lib5E_IsVulnerable| --&[%1%]| * 2 [Vulnerable] --<|<br />
--:_Lib5E_IsResistant| --&[%1%]| \ 2 [Resistant] --<|<br />
--:_Lib5E_IsImmune| --&[%1%]| * 0 [Immune] --<|<br />
</pre><br />
<br />
The idea is that the functions in the library create a string that can be appended to a roll to modify the output based on resistances, so you pass Lib5E_CheckDamageModifiers the name of the string variable you want to use and the damage type. The variable (ResistType in this case) will include either nothing, “* 2 [Vulnerable]”, “\ 2 [Resistant]”, or “* 0 [Immune]” which can be included in a roll assignment (--=) to modify the damage as appropriate. The order here might be important if an NPC is misconfigured to be both resistant and immune to the same damage type. Since immune is an absolute, having it last ensures that it will override resistant or vulnerable. A creature that is both vulnerable and resistant (again, misconfigured) will come back as resistant since that condition is checked after vulnerable.<br />
Some notes: I prefix my library labels with either “Lib5E_” or “_Lib5E_” as a clarity convention. This isn’t strictly necessary but you should be aware that if two libraries (or if your script and a library) define the same label, the last label defined will win. Since libraries are appended to the end of the script in the order you include them in the +++libname+++ directive, you can somewhat control this, but it is probably best to avoid re-declaring labels. <br />
<br />
In my case, items beginning with “Lib5E_” are intended to be called by scripts, while items beginning with “_Lib5E_” are intended to be used as subroutines by the “public” procedures. Of course, there is no reason you couldn’t call them directly.<br />
<br />
You might also note that I’ve included some library information in comment lines (--/|) at the top of the library. These are ignored by ScriptCards, and are a good way to convey requirements, parameters, usage information, etc.<br />
<br />
== Example Libraries ==<br />
<br />
=== dnd5elib ===<br />
<br />
[https://github.com/kjaegers/ScriptCards Download the dnd5elib Library from the ScriptCards GitHub]<br />
<br />
The '''dnd5elib''' library provides a collection of utility procedures that help simplify dealing with the D&D 5E Official Sheet. Some of the procedures in this library require '''chatsetattr''' to be installed in your game. This is a growing library, and currently only has a handful of routines. They are:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Procedure Name !! Notes<br />
|-<br />
| style="white-space:nowrap" | Lib5E_CheckDamageModifiers || This procedure can be used to evaluate vulnerabilities, resistances, and invulnerabilities on an NPC. After setting the --#target| parameters, pass the Lib5E_CheckDamageModifiers procedure a variable name (no reference information) and a damage type (i.e., fire, cold, bludgeoning, etc.) and a string variable with the name passed in as the first parameter will be created that contains text that can be included in a roll line (--=) in order to modify the roll as appropriate. For example, '''-->Lib5E_CheckDamageModifiers|ResistType;fire''' will check the current target character's attributes for "fire" and will either return an empty string (no references), "* 0 [Immune]" if the creature is immune, "\ 2 [Resistant]" if the creature is resistant, or "* 2 [Vulnerable]" if the creature is vulnerable to fire damage.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_DeductSpellSlot || Pass in a character_id and a slot level, and the script will expend one spell slot of that level, capping the value at 0 slots remaining. For Example '''<nowiki>-->Lib5E_DeductSpellSlot|@{selected|character_id};1</nowiki>''' to deduct a first level spell slot from the selected character.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_FindResource || Used to locate a resource value on a character. Pass in a character_id, a resource name, and two variable names. The procedure will check both repeating and non-repeating resources looking for a resource whose name matches what was passed in and return three variables. The first will be a string variable named for the 3rd parameter and contains the attribute name of the resource's "name" field. The second will be a string variable named after parameter 4 and contains the resource's value field attribute name, and the third variable is a Roll Variable, also named after the 4th parameter that contains the current resource value. Example: '''<nowiki>-->Lib5E_FindResource|@{selected|character_id};Crossbow bolts;ResName;ResValue</nowiki>''' will find "Crossbow bolts" as a resource on the character and return [&ResName] which is the name of the resource attribute, [&ResValue] which is the '''name of the attribute that stores the value''' and [$ResValue] which is the current numeric value of the resource.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Global_Attack_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Attack Modifiers (repeating_tohitmod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Bless" for 1d4 active and "Being Cool" for +2 active, I will get a return string " + 1d4 [Bless] + 2 [Being Cool]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Save_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Save Modifiers (repeating_savemod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Bless" for 1d4 active and "Being Cool" for +2 active, I will get a return string " + 1d4 [Bless] + 2 [Being Cool]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Skill_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Skill Modifiers (repeating_skillmod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Guidance" for 1d4 active and "Being Cool" for +2 active, I will get a return string " + 1d4 [Guidance] + 2 [Being Cool]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_AC_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Save Modifiers (repeating_savemod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Shield of Faith" with a value of 2 active, I will get a return string " + 2 [Shield of Faith]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Damage_Modifiers || Pass a character ID and TWO string variable to set the return value. The first string will be for normal damage, and the second will be the additional damage on a crit. This procedure will look through the Global Damage Modifiers (repeating_damagemod_*) for rows that are active (checked on the character sheet) and return two strings with the dice rolls and descriptions for them (for example, if I have "Sneak Attack" with a value of 1d6 normal and 1d6 critical damage active, I will get a return string " + 1d6 [Sneak Attack]" and another string of " + 1d6 [Sneak Attack CRIT]" that can be used in a dice rolls.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_DivineSmiteDice || Used to calculate the number of dice to be rolled for a paladin's Divine Smite. Pass a target token id, a spell slot level, and a string variable to be set to the dice roll amount based on the NPC_TYPE attribute of the target token. The returned variable will contain a dice roll (like "3d8" that can be used in a --= line)<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Character_Summary || Outputs a mini character sheet, including clickable buttons for attacks, actions, legendary actions, etc. Will automatically detect a PC vs NPC and output the appropriate sections.<br />
|}<br />
<br />
Due to formatting issues with the Wiki, the library code has been moved to a [https://gist.github.com/kjaegers/52f6049ddd257f0a1288aca4bbde13c5 GITHUB GIT]. Please view the GIST in raw mode and copy the text and paste it into a handout called "ScriptCards Library dnd5elib" in your Roll20 Game.<br />
<br />
== What to Know if you are Coming from PowerCards ==<br />
<br />
''Note: This section is a work in progress.''<br />
<br />
While ScriptCards and PowerCard have very similar output goals, their internals and use are quite different. The table below summarizes some of the major differences between the scripts.<br />
<br />
::{| class="wikitable"<br />
|-<br />
! PowerCards !! ScriptCards <br />
|-<br />
| With a handful of exceptions, all lines in a PowerCard macro are intended to produce a line of output on the final card. || With ScriptCards, ONLY the <code>--+</code> and <code>--*</code> statement types produces output <br />
|-<br />
| PowerCards lines begin with two dashes (<code>--</code>) followed by a unique tag name for the line, followed by a vertical bar and the content for the line. || ScriptCards lines begin with two dashes (<code>--</code>) followed by a '''statement type identifier''', which is a single character that identifies the type of line to the interpreter. This is followed by a tag (frequently optional), a vertical bar, and the parameters for the statement being executed.<br />
|-<br />
| PowerCard macros are always processed top to bottom. Lines can be hidden so they don't output anything, but there is no looping or branching (--SkipTo looks like a branch, but it just hides all of the lines until the referenced label. || ScriptCards scripts support true branching, including direct branching (<code>--^</code>) and procedure branching (<code>--></code>) and (<code>--<</code>). Procedures support parameters and a call stack so procedures can be nested to call other procedures.<br />
|-<br />
| All lines in a PowerCards macro need to have unique tags because PowerCards builds the card as a single JavaScript object using the tag names to store what will be displayed. This is why repeated tag names always result in the last one being shown. || ScriptCards tags do not need to be unique, and in the case of many line types are optional.<br />
|-<br />
| PowerCards conditionals result in either showing or hiding the line they are on. || ScriptCards conditionals '''''only''''' support branching as the result of the comparison. This branching can be direct (a GOTO) or procedural (a GOSUB) '''''NOTE: As of version 1.2.0, ScriptCards also supports roll/string variable assignment as a result of conditional evaluation'''''<br />
|-<br />
| PowerCards relies on the Roll20 [[Quantum Roll]] server and inline rolls for all dice functions || ScriptCards includes its own dice roll parser, and '''''does not support''''' inline rolls.<br />
|-<br />
| PowerCards RollIDs (often mistaken for variables) are assigned by analyzing the results of an inline roll, and cannot be referenced in other rolls, so you can't roll a <code>1d4</code> and then roll a <code>1d20</code> and add the <code>1d4</code> result because all of the rolls happen on the chat server before PowerCards gets the macro text. || ScriptCards supports two types of variables: Roll Variables and String Variables. Because ScriptCards uses its own roll parser and is not dependent upon the chat server, rolls and their results can be used in other rolls, math functions, output, etc.<br />
|}<br />
<br />
== Example Scripts ==<br />
<br />
Below are some sample scripts that utilize the various statement types in ScriptCards:<br />
<br />
=== Divine Smite ===<br />
<br />
This script will prompt the user for a spell slot level to expend on a divine smite. It will check the target's npc_type to see if it is an Undead or Fiend, which adds an additional d8 to the smite roll.<br />
<br />
[[File:ScriptCards Divine Smite.png|Divine Smite Script Output]]<br />
<br />
<pre><br />
!scriptcard {{<br />
--#title|Divine Smite<br />
--=DiceCount|?{Spell Slot Level?|1|2|3|4|5|6|7|8|9} + 1<br />
--=IsFiendOrUndead|0<br />
--?"@{target|npc_type}" -inc fiend|>IsBoosted<br />
--?"@{target|npc_type}" -inc undead|>IsBoosted<br />
--=TotalDice|[$DiceCount] + [$IsFiendOrUndead]<br />
--=SmiteRoll|[$TotalDice]d8<br />
--#emoteText|@{selected|token_name} smites @{target|token_name}<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
--+Smite|deals [$SmiteRoll] radiant damage.<br />
--X|<br />
<br />
--:IsBoosted|<br />
--=IsFiendOrUndead|1<br />
--<|<br />
}}<br />
</pre><br />
<br />
==== How It Works ====<br />
<br />
The first line sets the "title" card parameter to "Divine Smite".<br />
<br />
Line 2 Shows a query to the user asking for the spell slot level, adds one and stores the value in the "DiceCount" Roll Variable. The query/dropdown is generated by the chat server prior to the script being executed.<br />
<br />
Line 3 defaults the "IsFiendOrUndead" Roll Variable to 0.<br />
<br />
Lines 4 and 5 compare the target's "npc_type" attribute (passed by the chat server as text) to see if they include either "undead" or "fiend". If true, the IsBoosted subroutine will be called. No parameters are passed to this subroutine.<br />
<br />
Line 6 sets the "TotalDice" variable to the base (DiceCount) number plus the IsFiendOrUndead number, which will be a 0 or a 1.<br />
<br />
Line 7 calculates "SmiteRoll" by rolling a number of d8 equal to the "TotalDice" value.<br />
<br />
Lines 8-10 set the parameters for the emote, which appears above the card content. By setting the sourceToken and the targetToken, their icons will appear in the emote surrounding the text describing the action.<br />
<br />
Line 11 is the only line that actually produces output on the card. It results in "Smite deals # radiant damage".<br />
<br />
Line 12 ends the script execution, preventing the script from continuing and running the subroutines out of context.<br />
<br />
Lines 14-16 are the IsBoosted subroutine, starting with the :IsBoosted label. The IsFiendOrUndead variable is set to 1, and a return from subroutine is executed.<br />
<br />
=== Magic Missile ===<br />
<br />
This script demonstrates using a loop and calling a subroutine to fire a number of missiles determine by the spell slot level used to cast the spell.<br />
<br />
[[File:ScriptCards_MagicMissile_Fixed.png|Magic Missile Script Output]]<br />
<br />
<pre><br />
!scriptcard {{ <br />
--#title|Magic Missile<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
--=MissileCount|?{Spell Slot Level?|1|2|3|4|5|6|7|8|9} + 2<br />
--=DisplayCount|1<br />
--=MissileDamage|0<br />
--#leftsub|Slot level ?{Spell Slot Level?}<br />
--#rightsub|Ranged Attack<br />
--#emoteText|Fred uses a level ?{Spell Slot Level?} spell slot to fire [$MissileCount.Total] missiles of magical force!<br />
--:MissileLoop|<br />
-->FireMissile|<br />
--=DisplayCount|[$DisplayCount] + 1<br />
--?[$DisplayCount] -le [$MissileCount]|MissileLoop<br />
--+Total|Total damage is [$MissileDamage]<br />
--X|<br />
<br />
--:FireMissile|<br />
--=ThisMissile|1d4 + 1<br />
--=MissileDamage|[$MissileDamage] + [$ThisMissile]<br />
--+Missile|[$DisplayCount.Total] Hits for [$ThisMissile] [b]force[/b] damage<br />
--<|<br />
}}<br />
</pre><br />
<br />
==== How It Works ====<br />
<br />
Lines 1-3 set the card title, the source token and the target token. Setting these tokens causes their icons/avatars to appear in the Emote section of the card.<br />
<br />
Line 4 asks the user what spell slot level they wish to use to cast magic missile. The number of missiles fired is equal to 2 plus the spell level, and this is stored in the MissileCount variable.<br />
<br />
Line 5 stores a 1 in the DisplayCount variable. This will be used to control the loop to determine the number of missiles fired and the missile number when displaying damage rolls.<br />
<br />
Line 6 initializes MissileDamage to 0<br />
<br />
Line 7 sets the left subtitle to the text "Slot Level #", where # is the spell slot level being used.<br />
<br />
Line 8 sets the right subtitle to the text "Ranged Attack".<br />
<br />
Line 9 sets the emoteText parameter with a description of the action, including the slot level and number of missiles fired.<br />
<br />
Line 10 is a label for the missile firing loop<br />
<br />
Line 11 Calls the "FireMissile" subroutine<br />
<br />
Line 12 increases the DisplayCount variable by 1<br />
<br />
Line 13 Checks to see if there are still missles to fire (DisplayCount <= MissileCount) and if so branches to MissileLoop<br />
<br />
Line 14 Displays the total damage dealt by the spell.<br />
<br />
Line 15 stops execution of the script to prevent out of context execution of the subroutine.<br />
<br />
Lines 76-21 are the FireMissile subroutine, beginning with the FireMissile label. The 1d4+1 is rolled and assigned to "ThisMissile". The result is added to the existing MissileDamage total, and a line for the current missile is displayed with the missile number and the damage for the missile.<br />
<br />
=== Longsword Attack ===<br />
<br />
This script demonstrates a standard 5E D&D melee weapon attack, including detection of misses, fumbles, hits, and critical hits. If installed, alterbars is used to decrement the target's BAR3 value by the damage dealt.<br />
<br />
[[File:ScriptCards Longsword.png|Longsword Script Output]]<br />
<br />
<pre><br />
!scriptcard {{<br />
--#title|Longsword<br />
--#leftsub|Melee Attack<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
--#emoteText|@{selected|token_name} attacks @{target|token_name}<br />
--=TargetAC|@{target|npc_ac}<br />
--?[$TargetAC.Total] -gt 0|DoneWithAC<br />
--=TargetAC|@{target|ac}<br />
--:DoneWithAC|<br />
--=AttackRoll|1d20 + @{selected|strength_mod} [STR] + @{selected|pb} [PROF]<br />
--+Attack|@{selected|token_name} rolls [$AttackRoll] vs AC [$TargetAC].<br />
--?[$AttackRoll.Base] -eq 20|Crit<br />
--?[$AttackRoll.Base] -eq 1|Fumble<br />
--?[$AttackRoll.Total] -ge [$TargetAC.Total]|Hit<br />
--+Miss|The attack missed.<br />
--^Final|<br />
<br />
--:Fumble|<br />
--+Fumble!|The attack went horribly wrong.<br />
--^Final|<br />
<br />
--:Hit|<br />
--=Damage|1d8 + @{selected|strength_mod} [STR]<br />
--+Hit!|The attack hit @{target|token_name} for [$Damage] slashing damage.<br />
--@alter|_target|@{target|token_id} _bar|3 _amount|-[$Damage]<br />
--^Final|<br />
<br />
--:Crit|<br />
--=Damage|1d8 + @{selected|strength_mod} [STR] + 1d8 [CRIT]<br />
--+Critical Hit!|The attack hit @{target|token_name} for [$Damage] slashing damage.<br />
--@alter|_target|@{target|token_id} _bar|3 _amount|-[$Damage]<br />
<br />
--:Final|<br />
}}<br />
</pre><br />
<br />
==== How it Works ====<br />
<br />
In lines 1-5, we set the title, subtitle, and emote text along with the tokens for the emote area.<br />
<br />
Lines 6-9 allow us to determine the AC of the target. On the 5E Roll20 sheet, NPCs armor class is stored in "npc_ac", while PCs armor class is in "ac". First we grab npc_ac and if it is zero, we check AC.<br />
<br />
Line 10 rolls the attack roll, rolling 1d20 and adding the attacker's strength modifier and proficiency bonus<br />
<br />
Line 11 displays the result of the attack roll on the card<br />
<br />
Lines 12-14 determine what kind of result the attack had. If the .Base value of the roll was 20, we branch to "Crit". If it was 1, we branch to "Fumble". If the .Total value of the roll was greater than or equal to the AC that was determined in Lines 6-9, we branch to Hit.<br />
<br />
Assuming we didn't branc anywhere, the result of the attack was a miss, so we display that on line 15 and then branch to "Final"<br />
<br />
This is followed by three branch segments, :Fumble, :Hit, and :Crit. A fumble displays a text message and branches to :Final.<br />
<br />
On a hit or a crit, we roll Damage (adding additional damage dice on a crit). We display a "Hit!" or "Critical Hit!" message and then make an API call to AlterBars, passing it the token id, bar we want to modify (3 in this case), and the amount we want to modify by the Damage value.<br />
<br />
=== Party Health Status ===<br />
<br />
This example calculates the current Hit Points remaining and HP percentage for each character and creates a color-coded display with the current party status.<br />
<br />
[[File:ScriptCards Party Health.png]]<br />
<br />
<pre><br />
!scriptcard {{<br />
--#title|Party Status<br />
--#titleCardBackground|#33CC33<br />
--#oddrowbackground|#bfee90<br />
--#evenrowbackground|#90eebf<br />
-->HealthCheck|@{Quej Grastra|character_id}<br />
-->HealthCheck|@{Brim Cheuto|character_id}<br />
-->HealthCheck|@{Odug Ututees|character_id}<br />
--X|End of card Execution<br />
<br />
--:HealthCheck|<br />
--=HealthPerc|[*[%1%]:hp] / [*[%1%]:hp^] * 100 \ 1<br />
--=HealthColor|000000<br />
--?[$HealthPerc.Total] -gt 50|HealthSkip<br />
--=HealthColor|FF0000<br />
--:HealthSkip|<br />
--+[*[%1%]:character_name]|has [#[$HealthColor.RollText]][*[%1%]:hp] of [*[%1%]:hp^][/#] HP [R]([$HealthPerc.Total]%)[/R]<br />
--<|End of HealthCheck<br />
}}<br />
</pre><br />
<br />
==== How it Works ====<br />
<br />
Lines 1-4, we set the card title, and set the title background and row background colors to shades of green.<br />
<br />
Lines 5-7 make gosub calls the the "HealthCheck" subroutine, passing in the character ID of each of the named characters (these are the names of the characters in my test game)<br />
<br />
Line 8 terminates the script execution.<br />
<br />
The remaining lines of the script are the HealthCheck subroutine, which works like this:<br />
<br />
Line 10 is the subroutine label (:HealthCheck)<br />
<br />
Line 11 uses the character id passed as a parameter and combines it with character attribute lookup *(...) to retrieve the value of "hp" and "hp<nowiki>^</nowiki>" for the character. The <nowiki>^</nowiki> character is used to specify that we want the MAX value for this attribute for the second call. We divide these two numbers and multiple by 100 to get a percentage. Finally, we use integer division by 1 to round the percentage and drop the decimals. The end result gets stored in the HealthPerc roll variable.<br />
<br />
Line 12 defaults to color of the health text to black<br />
<br />
Line 13 check to see if the health percentage is greater than 50. If so, it branches to HealthSkip, preventing the script from executing line 13.<br />
<br />
Line 14 sets the color of the health text to red<br />
<br />
Line 15 is the label that will be branched to from Line 13 to skip the red coloring<br />
<br />
Line 16 again uses character attribute substitution and the passed parameter value to output a display line containing the character name, the colorized health total, and the percentage value. The percentage is right-justified.<br />
<br />
Line 17 returns from the HealthCheck subroutine.<br />
<br />
=== Expanded Magic Missile Script ===<br />
<br />
This is the expanded and enhanced version of the Magic Missile script covered in {{yt|watch?v=u50xvNzS9Zk | this video}}. It includes visual and audio effects, checking and deducting spell slots, and applying damage using either Token-Mod or Alterbars.<br />
<br />
<pre><br />
!scriptcard {{ <br />
--#title|Magic Missile<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
<br />
-->GetAndCheckSlotInformation|<br />
<br />
--=MissileCount|[$SlotLevel] + 2<br />
--=DisplayCount|1<br />
--=MissileDamage|0<br />
--#leftsub|Slot level [$SlotLevel]<br />
--#rightsub|Ranged Attack<br />
--#emoteText|@{selected|character_name} uses a level [$SlotLevel.Total] spell slot to fire [$MissileCount.Total] missiles of magical force!<br />
<br />
--:MissileLoop|<br />
-->FireMissile|<br />
--=DisplayCount|[$DisplayCount] + 1<br />
--?[$DisplayCount] -le [$MissileCount]|MissileLoop<br />
--+Total|Total damage is [$MissileDamage]<br />
-->DeductSpellSlot|<br />
--#rightsub|Level [$SlotLevel] Left: [$SlotsRemaining] <br />
-->PlayEffects|none;burst-smoke;beam-magic;spell_01<br />
-->ApplyDamageTokenmod|@{target|token_id};3;-[$MissileDamage]<br />
-->ApplyDamageAlterbars|@{target|token_id};3;-[$MissileDamage]<br />
--X|<br />
<br />
--:FireMissile|<br />
--=ThisMissile|1d4 + 1<br />
--=MissileDamage|[$MissileDamage] + [$ThisMissile]<br />
--+Missile|[$DisplayCount.Total] Hits for [$ThisMissile] [b]force[/b] damage<br />
--<|<br />
<br />
--:GetAndCheckSlotInformation|<br />
--=SlotLevel|?{Spell Slot Level?|1|2|3|4|5|6|7|8|9}<br />
--=SlotsTotal|[*S:lvl[$SlotLevel]_slots_total]<br />
--=SlotsExpended|[*S:lvl[$SlotLevel]_slots_expended]<br />
--?[$SlotsExpended.Total] -ge [$SlotsTotal.Total]|NoSlotsLeft<br />
--<|<br />
<br />
--:NoSlotsLeft|<br />
--+|[*S:character_name] has no level [$SlotLevel.Total] spell slots available.<br />
--X|<br />
<br />
--:DeductSpellSlot|<br />
--=SlotsExpended|[$SlotsExpended] + 1<br />
--@setattr|_charid [*S:character_id] _lvl[$SlotLevel]_slots_expended|[$SlotsExpended] _silent<br />
--=SlotsRemaining|[$SlotsTotal] - [$SlotsExpended]<br />
--<|<br />
<br />
--:PlayEffects|Parameters are : source effect; target effect; line effect; sound effect<br />
--vtoken|@{selected|token_id} [%1%]<br />
--vtoken|@{target|token_id} [%2%]<br />
--vbetweentokens|@{selected|token_id} @{target|token_id} [%3%]<br />
--@roll20AM|_audio,play,nomenu|[%4%]<br />
--<|<br />
<br />
--:ApplyDamageTokenmod|Parameters are tokenid;bar#;amount<br />
--@token-mod|_ignore-selected _ids [%1%] _set bar[%2%]_value|[%3%]<br />
--<|<br />
<br />
--:ApplyDamageAlterbars|<br />
--@alter|_target|[%1%] _bar|[%2%] _amount|[%3%]<br />
--<|<br />
}}<br />
</pre><br />
<br />
[[Category:Featured articles]]</div>5004103https://wiki.roll20.net/Script:ScriptCardsScript:ScriptCards2021-09-28T08:15:35Z<p>5004103: /* Echo to Chat (--e) */</p>
<hr />
<div>{{revdate}}<br />
== Introduction ==<br />
'''ScriptCards''' provides a script interpreter that can be used to create powerful macros that display the results of player/NPC actions, or display other information in a pleasing visual format in your game's chat window. The scripting language contains variables (both dice-roll (enhanced numerics) and strings) as well, conditionals, branching, subroutines with parameters, and a set of built-in functions to simplify working with Roll20 information.<br />
{{script overview<br />
|name=ScriptCards<br />
|author={{user profile|2365448|Kurt J.}}<br />
|code=<br />
|version=1.4.0e<br />
|lastmodified=2021-09-24}}<br />
ScriptCards is not game-system specific, and can be used with any system/sheet. Near the end of this Wiki there is a section set aside for libraries that can implement system-specific tasks, with the hope that enthusiasts playing particular systems will create and share utility functions that can be utilized by the wider community.<br />
<br />
The default display style for ScriptCards output is similar to the format used to document player and NPC abilities in Dungeons and Dragons 4th Edition, but does not have any system ties to D&D4E.<br />
<br />
Current OneClick Version : 1.4.0e<br />
<br />
Current Development Version : 1.4.4<br />
<br />
'''''<big>Critically Important: ScriptCards does not use/parse inline rolls. ScriptCards includes its own built-in dice roll parser to allow for the use of variables inside dice rolls. As of version 1.2.3, ScriptCards will now take inline rolls and substitute the total result value in statement strings, meaning that you can utilize inline rolls but ScriptCards will only see the result of the roll, and not parse the roll components itself.</big>'''''<br />
<br />
* {{fpl|9752053/ ScriptCards thread}}<br />
** {{fpl|10000297/ Scritpcard API Working and Sharing}}<br />
* https://github.com/kjaegers/ScriptCards/tree/main/ScriptCards_API - GitHub repository for source before the one-click version is updated.<br />
* {{yt.be|hyR7Jnq4mQM ScriptCards Intro}} 45min, Jan 2021<br />
* {{yt.be|u50xvNzS9Zk ScriptCards Magic Missile Deep Dive}} 39min, Feb 2021<br />
<br />
<br />
__TOC__<br />
=== Is ScriptCards Related to [[PowerCards]]? ===<br />
<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
Check the '''[[#What to Know if you are Coming from PowerCards|What to Know if you are Coming from PowerCards]]'''-section for a comparison table between the two scripts.<br />
<br />
== What is a ScriptCard Script ==<br />
<br />
A ScriptCard Script is text written into the chat window (either typed directly, pasted, or run via a macro) that will produce a card of information in the [[text Chat|chat window]]. A ScriptCard Script is composed of an [[API]] command: <code><nowiki>!scriptcard {{ }}</nowiki></code> enclosing any number of lines that determine the output that will be added to the card. At it simplest, the following macro:<br />
<br />
<pre>!scriptcard {{ }}</pre><br />
<br />
Will produce just a title card that displays “ScriptCards” as the name:<br />
<br />
[[File:Scriptcard blank.png]]<br />
<br />
Of course, this is just the simplest type of macro and isn’t very useful. In order to produce useful output, we need to include lines between the <code><nowiki>{{</nowiki></code> and <code><nowiki>}}</nowiki></code> that direct the API script as to what it should do.<br />
<br />
== Structure of a ScriptCard Line ==<br />
<br />
All ScriptCard lines begin with two dashes, followed by an ''statement identifier character'' that lets ScriptCards what type of line it is. There are several of these, and they are detailed in the next section. After the line type identifier, a Tag name 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.<br />
<br />
Following the Tag is a vertical bar, and then the content of the line itself. Again, each type of line might interpret this content differently.<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Identifier !! Statement Type !! Tag !! Content !! Notes<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--/</nowiki> || Comment || unused || unused || The <code>--/</code> 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--#</nowiki> || 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").<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--+</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--=</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--&</nowiki> || Assign String 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. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--@</nowiki> || 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 (i.e., [[TokenMod|!token-mod]], or [[ChatSetAttr|!setattr]], etc.)<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--:</nowiki> || 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<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--^</nowiki> || Branch To || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--></nowiki> || Call Procedure || 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<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--<</nowiki> || 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.<br />
|- <br />
| style="white-space:nowrap" | <nowiki>--?</nowiki> || Conditional Branch || Condition to be evaluated || True Branch Label<nowiki>|</nowiki>False Branch Label || The condition will be evaluated and execution will jump to one of the two indicated branches (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 included a semicolon separated list of parameters. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--s</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--l</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--v</nowiki> || 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+'''''<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--e</nowiki> || Echo to Chat || Name to send chat command as || Chat message to send || Variable substitution takes place on the tag and content.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--R</nowiki> || Retrieve Repeating Section Row information || "find", "first", or "next" || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--~</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--c</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--i</nowiki> || Information Request || User Prompt;Button Caption || InfoType;VariableName;ParameterText || See full documentation below.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--d</nowiki> || 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. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--%</nowiki> || 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. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--*</nowiki> || 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.<br />
|}<br />
<br />
== ScriptCard Statement Type Details ==<br />
The sections below detail the individual statement types supported by ScriptCards<br />
<br />
=== Comment (--/) ===<br />
<br />
A --/ statement is ignored by the ScriptCards parser. You can use this type of statement to add comments and informational text to your script. <br />
<br />
Example:<br />
<pre><br />
!script {{<br />
--/|Script Name : Fireball<br />
--/|Purpose : Allow the player to cast a fireball and blow stuff up!<br />
.<br />
.<br />
.<br />
}}<br />
</pre><br />
<br />
=== Set Parameter (--#) ===<br />
<br />
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.<br />
<br />
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.<br />
<br />
'''''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.'''''<br />
<br />
Examples:<br />
<pre><br />
--#title|Magic Missile<br />
--#leftsub|Level 1 Spell<br />
--#rightsub|Force Damage<br />
</pre><br />
<br />
The three examples above set the “title”, “leftsub”, and “rightsub” values for the card to the content value for the line. <br />
<br />
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.<br />
Settings Lines do not produce output lines on the card.<br />
<br />
The following settings are available (note that parameter names are ''not'' case sensitive):<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Name !! Effect/Use !! Default Value !! Type<br />
|-<br />
| 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<br />
|-<br />
| allowplaintextinrolls || If set to a non-zero value, plain character text in rolls will be copied to the roll text || 0 || Per-Line<br />
|-<br />
| bodyFontFace || Name of the font used in the card rows || Helvetica || Global<br />
|-<br />
| bodyFontSize || Size of the text in the card rows || 14px || Global<br />
|-<br />
| bodybackgroundimage || Specify an image (content for a CSS background-image tag) for the body area || none || Global<br />
|-<br />
| buttonBackground || Background color for buttons created with [button][/button] || #1C6EA4 || Per-Line<br />
|-<br />
| buttonBorderColor || Border (outline) color for buttons created with [button][/button] || #999999 || Per-Line<br />
|-<br />
| buttonFontFace || Font Family specifier for captions on buttons created with [button][/button] || Tahoma || Per-Line<br />
|-<br />
| buttonFontSize|| Text size for captions on buttons created with [button][/button] || x-small || Per-Line<br />
|-<br />
| buttonTextColor|| Text color of labels on buttons created with [button][/button] || #FFFFFF || Per-Line<br />
|-<br />
| 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<br />
|-<br />
| deferralcharacter || Changes the meta script deferral sequence to the specified value || ^ || Per-Line<br />
|-<br />
| diceFontColor|| Color of the dice created with the [d4] [d6], etc. formatting markers || #1C6EA4 || Per-Line<br />
|-<br />
| dicefontsize || Size of the dice created with the [d4] [d6], etc. formatting markers || 3.0em || Per-Line<br />
|-<br />
| 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<br />
|-<br />
| disablerollprocessing || If set to a non-zero value, --= lines will not process dice rolls strings || 0 || Per-Line<br />
|-<br />
| emoteBackground || Background color of the emote area || #f5f5ba || Global<br />
|-<br />
| emoteFont || Name of the font used in emote area (above the title of the output card) || Georgia || Global<br />
|-<br />
| emoteFontColor || Color of the font in the emote area || None (Empty) || Global<br />
|-<br />
| emoteFontSize || Size of the font used in the emote area || 14px || Global<br />
|-<br />
| emoteFontWeight || Font weight for the font in the emote area || bold|| Global<br />
|-<br />
| emoteState || If set to anything other than "visible", the emote portion of the card will not be displayed || visible || Global<br />
|-<br />
| emoteText || Text to display in the emote portion of the card || None (Empty) || Global<br />
|-<br />
| emotefont || Name of the font used in the emote text area || font-family: Georgia, serif; font-weight: bold; || Global<br />
|-<br />
| evenRowBackground || Hex code for the background color for even rows || #eeeeee || Per-Line<br />
|-<br />
| evenRowFontColor || Hex code for the text color for even rows || #000000 || Per-Line<br />
|-<br />
| evenrowbackgroundimage || Specify an image (content for a CSS background-image tag) for the even card rows || none || Per-Line<br />
|-<br />
| executionlimit || Maximum number of script lines the interpreter will try to execute. This prevents "infinite loop" sandbox crashes || 40000 || Global<br />
|-<br />
| hideCard || If set to any non-default value, the entire card output will be suppressed || 0 || Global<br />
|-<br />
| 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<br />
|-<br />
| 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<br />
|-<br />
| lineheight || Vertical size of each line on the output card || normal || Per-Line<br />
|-<br />
| nominmaxhighlight || If set to anything other than "0", rolls will not display crit/fumble/mixed highlight colors. || 0 || Per-Line<br />
|-<br />
| norollhighlight || If set to anything other than "0", rolls will not be formatted (plain numbers) but will still get a tooltip with details ('''''v1.3.6b+''''') || 0 || Per-Line<br />
|-<br />
| oddRowBackground || Hex code for the background color for even rows || #d0e4f5 || Per-Line <br />
|-<br />
| oddRowFontColor || Hex code for the text color for odd rows || #000000 || Per-Line<br />
|-<br />
| oddrowbackgroundimage || Specify an image (content for a CSS background-image tag) for the odd crd rows || none || Per-Line<br />
|-<br />
| reentrant || Used to name a script for rentrant button use || 0 || Global<br />
|-<br />
| 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)0 || Global<br />
|-<br />
| rollhilightlineheight || Determines the height of the hilight box placed around roll results ('''''1.4.2+''''') || 1.0em || Per-Line<br />
|-<br />
| roundUp || If set to a non-default value, integer division will round up instead of down || 0 || Per-Line<br />
|-<br />
| showfromfornonwhispers || If set to a non-zero value, will include the sender on cards that aren't whispered || 0 || Global<br />
|-<br />
| 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<br />
|-<br />
| subtitleFontColor || Color of the text in the subtitle areas || #FFFFFF || Global<br />
|-<br />
| subtitleFontFace || Name of the font used on the subtitle sections || Tahoma || Global<br />
|-<br />
| subtitleFontSize || Size of the subtitle font || 13px || Global<br />
|-<br />
| subtitleSeperator || The character(s) that will be placed between leftsub and rightsub || <nowiki>&#x2666</nowiki>; || Global<br />
|-<br />
| tableBorderRadius || CSS specifier for how rounded the borders of the output card are. Use "0px;" for square borders || 6px; || Global<br />
|-<br />
| tableShadow || CSS specifier for the drop shadow under the output card || 5px 3px 3px 0px #aaa; || Global<br />
|-<br />
| tablebgcolor || Background color of the whole card. '''''Normally not visible''''' || #EEEEEE || Global<br />
|-<br />
| tableborder || Color of the border that surrounds the whole card || 2px solid #000000; || Global<br />
|-<br />
| 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<br />
|-<br />
| timezone || IANA Specifier for the local time zone, used in system/date functions || merica/New_York || Per-Line<br />
|-<br />
| title || Text displayed in the title area of the card || ScriptCards || Global<br />
|-<br />
| titleCardBackground || A hex color code representing the background color of the title area. || #1c6ea4 || Global<br />
|-<br />
| titleFontColor || Color of the text on the card title || #FFFFFF || Global<br />
|-<br />
| titleFontFace || Name of the font used on the title area || Contrail One || Global<br />
|-<br />
| titleFontLineHeight || Line spacing on the title area || 1.2em || Global<br />
|-<br />
| titleFontSize || Size of the title font || 1.2em || Global<br />
|-<br />
| titlecardbackgroundimage || Specify an image (content for a CSS background-image tag) for the title card area || none || Global<br />
|-<br />
| titlecardbottomborder || Border CSS specifier for the bottom of the title card area || 2px solid #444444; || Global<br />
|-<br />
| titlecardgradient || If set to non-zero value, will place a vertical gradient on the title card area || 0 || Global<br />
|-<br />
| usehollowdice || If set to a non-zero value, the hollow/outline versions of the dice fonts will be used || 0 || Per-Line<br />
|-<br />
| whisper|| Comma separated list of who to whisper the output to. Use "gm" for [[GM|GMs]] and "self" for the sender || none || Global|}<br />
|}<br />
<br />
''Setting Lines do not produce output lines on the card''<br />
<br />
=== Direct Output (--+) ===<br />
<br />
A direct output line display 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.<br />
<br />
Examples of Direct Output lines:<br />
<pre><br />
--+Hello|World<br />
--+Attack|The monster rolls [$Attack] to hit!<br />
--+Damage|@{target|token_name} is hit for [$Damage] [#3333AA][b]frost[/b][/#] damage.<br />
</pre><br />
<br />
Direct Output lines support inline formatting, roll variable replacement, character attribute references, and procedure variables.<br />
<br />
=== GM Output (--*) ===<br />
<br />
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. <br />
<br />
Example:<br />
<pre><br />
--+PlayerLine|This line is shown on the public card<br />
--*GMLine|This line will only be shown to GMs, on a separate card.<br />
</pre><br />
<br />
=== Roll Variable Assignment (--=) ===<br />
<br />
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.<br />
<br />
'''''All components of a roll equation should be separated with spaces.'''''<br />
<br />
Examples:<br />
<pre><br />
--=MissileDamage|1d4 + 1<br />
--=Attack|1d20 + @{selected|strength_mod} [STR] + @{selected|pb} [PROF]<br />
</pre><br />
<br />
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. Text enclosed in square brackets ([]) is considered "flavor text" and will be added to the result text but does not impact the roll result.<br />
<br />
The following dice formats are supported:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Format Pattern !! Example !! Description<br />
|-<br />
| XdY || 3d8 || Simple format. Roll a Y-sided die X times<br />
|-<br />
| XdYkhZ || 2d20kh1 || Roll Y-sided die X times and keep the highest Z number of dice<br />
|-<br />
| XdYklZ || 4d6kl3 || Roll Y-sided die X times and keep the lowest Z number of dice <br />
|-<br />
| XdY>Z || 5d6>3 || Roll Y-sided die X times and count a 1 for each roll greater than Z <br />
|-<br />
| XdY<Z || 5d6<3 || Roll Y-sided die X times and count a 1 for each roll less than Z <br />
|}<br />
<br />
'''''Note: The dice formulae below are supported in the development version of ScriptCards and will be merged with the table above when activated on OneClick'''''<br />
::{| class="wikitable"<br />
|-<br />
! Format Pattern !! Example !! Description<br />
|-<br />
| 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<br />
|-<br />
| 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<br />
|-<br />
| 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)<br />
|-<br />
| 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<br />
|}<br />
<br />
The following operators are supported in a roll equation:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Operator !! Operation<br />
|-<br />
| + || Addition <br />
|-<br />
| - || Subtraction <br />
|-<br />
| * || Multiplication <br />
|-<br />
| / || Division <br />
|-<br />
| \ || Integer Division (Rounds down) <br />
|-<br />
| % || Modulo (Remainder of Divison)<br />
|}<br />
<br />
Roll Variables can be accessed at any time after they have been created by using the [$VariableName] format, with the following optional modifiers:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Modifier !! Meaning<br />
|-<br />
| No modifier || In a Direct Output Line (<nowiki>--+</nowiki>) 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<br />
|-<br />
| .Total || The end result of the roll equation as an unformatted number <br />
|-<br />
| .Base || The cumulative result of any dice rolled in the Roll Text (Numeric modifiers are not included) <br />
|-<br />
| .Ones || The number of dice in the roll that came up as 1s <br />
|-<br />
| .Aces || The number of dice in the roll that came up as the maximum number on the die <br />
|-<br />
| .Odds || The number of dice in the roll that came up with an odd number <br />
|-<br />
| .Evens || The number of dice in the roll that came up with an even number <br />
|-<br />
| .RollText || The raw text of the roll that was use to generate the results <br />
|-<br />
| .Text || A text representation of the results of the roll, including the numbers rolled for each die <br />
|-<br />
| .tableEntryText || The text portion of the result of a table roll<br />
|-<br />
| .tableEntryImgURL || The image source portion of the result of a table roll<br />
|-<br />
| .tableEntryValue || Numeric value of tableEntryText (via parseInt). If a non-numeric value, will be 0<br />
|-<br />
| .Raw || The total numeric result without any formatting, even if placed somewhere formatting would normally be done. <br />
|}<br />
<br />
Examples:<br />
<pre><br />
--+Total Damage|[$MissileDamage.Total] (roll was 1d4+1)<br />
--+Base Damage|[$MissileDamage.Base] (without the +1)<br />
--=Attack|1d20 + @{selected|strength_mod} [STR] + @{selected|pb} [PROF] + [$BlessBonus] [Bless]<br />
</pre><br />
<br />
In this case, 1d4 will be rolled and stored in “BlessBonus”, which can then be used in the Attack line.<br />
<br />
'''''Mathematical Functions in Roll Expressions '''''<br />
<br />
The ScriptCards roll parser works from left to right, always maintaining a current value and applying whatever comes next to the total. The following in-line functions to the roll parser. These are:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Expression !! Meaning<br />
|-<br />
| {ABS} || Absolute Value<br />
|-<br />
| {CEIL} || Ceiling value (round up to the next whole number)<br />
|-<br />
| {FLOOR} || Floor value (round down to the next whole number)<br />
|-<br />
| {ROUND} || Round value (round up if the decimal portion is greater than 0.5, otherwise round down)<br />
|-<br />
| {NEGATE} || Multiply the value by negative one.<br />
|-<br />
| {SQRT} || Take the square root of the running value. ('''''1.4.1+''''')<br />
|-<br />
| {SQUARE} || Square the running value. ('''''1.4.2+''''')<br />
|-<br />
| {CUBEROOT} || Take the cube root of the running value. ('''''1.4.2+''''')<br />
|-<br />
| {CUBE} || Cube the running value. ('''''1.4.2+''''')<br />
|-<br />
| {SIN} || Return the SIN of running value. ('''''1.4.2+''''')<br />
|-<br />
| {COS} || Return the COS of running value. ('''''1.4.2+''''')<br />
|-<br />
| {TAN} || Return the TAN of running value. ('''''1.4.2+''''')<br />
|-<br />
| {ASIN} || Return the ASIN of running value. ('''''1.4.2+''''')<br />
|-<br />
| {ACOS} || Return the ACOS of running value. ('''''1.4.2+''''')<br />
|-<br />
| {ATAN} || Return the ATAN of running value. ('''''1.4.2+''''')<br />
|}<br />
<br />
<br />
'''''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 <nowiki>[[ ]]</nowiki> 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.<br />
<br />
'''''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.<br />
<br />
'''Rolling on Rollable Tables'''<br />
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.<br />
<br />
''Roll Variable Lines do not produce output lines on the card.''<br />
<br />
=== String Variable Assignment (--&) ===<br />
<br />
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:<br />
<br />
<pre><br />
--&MyText|Hello<br />
</pre><br />
<br />
Here, we assign the text "Hello" to the string variable named MyText. You can also append text to a string variable by prefixing the content with a + sign:<br />
<br />
<pre><br />
--&MyText|+ World<br />
</pre><br />
<br />
If run after the statement above, MyText will now contain "Hello World".<br />
<br />
String variables can be referenced using the syntax [&variablename]<br />
<br />
=== Call API (--@) ===<br />
<br />
ScriptCards can use a Call API instruction to execute other API commands. The Tag contains the API 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 API command is executed.<br />
<br />
Examples:<br />
<pre><br />
--@eh|list<br />
--@alter|_target|@{target|token_id} _bar|3 _amount|-[$Damage]<br />
</pre><br />
<br />
In the first example above, the command <code>!eh list</code> will be executed, calling [[EncounterHelper]]. In the second, {{fpl|1216260/ AlterBars}} is called to modify a token's Bar 3 value.<br />
<br />
'''''Note:''''' When ScriptCards (or any API script) runs other API 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).<br />
<br />
See [[API:Script Index]] for more options.<br />
<br />
=== Branch Label (--:) ===<br />
<br />
A branch label defines a line in your code that can be reached by one of the branching instructions (<nowiki>--^</nowiki>, <nowiki>--></nowiki>, or <nowiki>--?</nowiki>). The Tag serves as the label name, and must be unique on the card.<br />
<br />
The vertical bar (|) separator must be present, but the content portion of the line is unused and can be treated as a comment.<br />
<br />
Examples:<br />
<pre><br />
--:MyLoop|<br />
--:CriticalHit|Will jump here if we roll a critical hit!<br />
</pre><br />
<br />
''A Branch Label line does not produce an output line on the card.''<br />
<br />
=== Branch (--^) === <br />
<br />
A Branch line 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.<br />
<br />
Examples:<br />
<pre><br />
--^MyLoop|Jumps to MyLoop<br />
--^SkipCrit|We didn't crit, so skip the Crit code<br />
</pre><br />
<br />
''A Branch line does not produce an output line on the card.''<br />
<br />
=== Call Procedure (-->) ===<br />
<br />
Similar to a branch, a Call Procedure (sometimes knows 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 (<nowiki>--<</nowiki>) 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 (;).<br />
<br />
Examples:<br />
<pre><br />
-->FixFormat|#3333FF;#999999<br />
</pre><br />
<br />
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%].<br />
<br />
=== Return (--<) ===<br />
<br />
A return instruction marks the end of a Gosub procedure. 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.<br />
<br />
Examples:<br />
<pre><br />
--<|<br />
--<|End of MySub<br />
</pre><br />
<br />
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.<br />
<br />
=== Conditional Statement (--?) ===<br />
<br />
A conditional statement contains some equation in the Tag that will be evaluated. '''''If any part of the comparison can/does contain a space, it needs to be surrounded by double quotes'''''<br />
<br />
Based on the true/false result of the evaluation, one of two execution paths will be taken. These execution paths are detailed in the content section of the statement. The "if true" path is specified first (directly after the vertical bar), and the "if false" path is specified after it, also separated by a vertical bar.<br />
<br />
Example:<br />
<pre><br />
--?[$AttackRoll.Total] -ge [$TargetAC]|Hit|Miss<br />
</pre><br />
<br />
'''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.'''<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Branch Format !! Meaning<br />
|-<br />
| Label || If just a label is specified, execution will branch to that label when the comparison is matched.<br />
|-<br />
| >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 <br />
|-<br />
| =VariableName || The roll variable "VariableName" will be assigned the value following a semicolon (ex: --?1 -eq 1|=Roll;1d20)<br />
|-<br />
| &VariableName || The string variable "VariableName" will be assigned the value following a semicolon (ex: --?1 -eq 1|&Result;Hit|&Result;Miss)<br />
|-<br />
| % or %! || The current for...next loop will perform the "next" action (%) or will break out (%!) <br />
|-<br />
| [ || Code block (see below)<br />
|}<br />
<br />
Examples:<br />
<pre><br />
--?[$AttackRoll.Base] -eq 20|CriticalHit<br />
--?[$AttackRoll.Base] -eq 1|>Fumble;@{selected|dexterity_mod}<br />
--?"@{target|npc_type}" -inc "undead"|&MonsterType;Undead|&MonsterType;Not Undead<br />
--?[$Attack.Total] >= [$ArmorClass]|>Hit|>Miss<br />
</pre><br />
<br />
In the first example, if the Base value of AttackRoll is a 20 (natural 20 on the die) execution will branch to the CriticalHit label.<br />
<br />
In the second example, 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%].<br />
<br />
The third example looks for the word "undead" in the npc_type attribute of the targeted character. If it exists in the text, the MonsterType string variable will be set to "Undead", otherwise it will be set to "Not Undead". <br />
<br />
The final example would call 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.<br />
<br />
''Text that does/may contain a space should be enclosed in double quotes.''<br />
<br />
The following comparison operators are available:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Comparator !! Meaning<br />
|-<br />
| -eq || Equal To <br />
|-<br />
| -eqi || Case insensitive Equal To <br />
|-<br />
| -ne || Not Equal To <br />
|-<br />
| -nei || Case insensitive Not Equal To <br />
|-<br />
| -gt || Greater Than <br />
|-<br />
| -ge || Greater Than or Equal To <br />
|-<br />
| -lt || Less Than <br />
|-<br />
| -le || Less Than or Equal To <br />
|-<br />
| -inc || Includes (text strings). <br />
|-<br />
| -ninc || Does Not Include (text strings). <br />
|}<br />
<br />
Multi-part conditionals are supported with -and and -or as separators. For example:<br />
<br />
<pre><br />
--?[$Attack.Total] -ge @{target|npc_ac} -and [$Attack.Base] -ne 20|HitButNotCrit<br />
</pre><br />
<br />
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):<br />
<br />
true AND false OR true<br />
<br />
Will be evaluated as true. The first two (true and false) will be false, but then false OR true will be true.<br />
<br />
Conversely:<br />
<br />
true or false and false<br />
<br />
Will be false, because the first true and false will evaluate to true, and then true and false will be false.<br />
<br />
'''CODE BLOCKS'''<br />
<br />
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.<br />
<br />
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:<br />
<br />
<pre><br />
!script {{<br />
--=Roll|1d2<br />
--+Roll|[$Roll]<br />
--?[$Roll.Total] -eq 2|[<br />
--&Value|Yep!<br />
--+|We are inside the TRUE portion of the block<br />
--]|[<br />
--&Value|Nope<br />
--+|We are inside the FALSE portion of the block<br />
--]|<br />
--+After|the blocks!<br />
--+Value|[&Value]<br />
}}<br />
</pre><br />
<br />
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 --]|. <br />
<br />
At this time, blocks cannot be nested, and can only be created as part of a conditional (--[ is not a valid statement type)<br />
<br />
''A conditional statement does not produce a line of output on the card.''<br />
<br />
=== Case Statement (--c) ===<br />
<br />
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 (:). Each match condition includes a branch label that will be used if the test value matches the item. 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:<br />
<br />
<pre><br />
!script {{<br />
--#title|Case Statement Testing<br />
--=Roll|1d4<br />
--C[$Roll.Total]|1:>One;[$Roll]|2:>Two;[$Roll]|3:>Three;[$Roll]|4:>Four;[$Roll]<br />
--X|<br />
<br />
--:One| --+Value|was One ([%1%]) --<|<br />
--:Two| --+Value|was Two ([%1%]) --<|<br />
--:Three| --+Value|was Three ([%1%]) --<|<br />
--:Four| --+Value|was Four ([%1%]) --<|<br />
}}<br />
</pre><br />
<br />
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 variable as a parameter.<br />
<br />
=== Save and Load (--s and --l) ===<br />
<br />
This statement pair is used to either store (--s) or load (--l) data from persistent storage. Items stored in persistent storage remain between card rolls and between Roll20 sessions. There are two types of data that can be stored: settings and roll variables. <br />
<br />
Examples:<br />
<br />
<pre><br />
--Ssettings|GreenStyle<br />
--Srollvariables|FirstCardVars<br />
</pre><br />
<br />
In this case, the tag for the statement determines what type of item is being saved (settings or rollvariables). When saving settings, all non-default settings are written to the named setting storage value. When Roll Variables are saved, all variables that currently exist will be saved to the named storage value.<br />
<br />
Loading stored items simply requires the same command with the --l statement type:<br />
<br />
<pre><br />
--Lsettings|GreenStyle<br />
--Lrollvariables|FirstCardVars<br />
</pre><br />
<br />
When loading settings, all stored settings will be applied to the current card settings. You can override settings by changing them after the load.<br />
<br />
When loading roll variables, the saved variables will be added to (or overwrite if they have the same name) any variables on the current card. This means it is safe to create roll variables before the load statement.<br />
<br />
'''Practical Uses'''<br />
The major intended use of persistent storage is for storing card formats for use in later scripts. For example, the following script:<br />
<br />
<pre><br />
!scriptcard {{<br />
--#titlecardbackground|#22CC22<br />
--#oddrowbackground|#cceecc<br />
--#evenrowbackground|#99ee99<br />
--Ssettings|@{selected|token_name}<br />
}}<br />
</pre><br />
<br />
Would save the titlecardbackground, oddrowbackground, and evenrowbackground settings to a saved list named after the selected token's name. When creating cards for that token to run later, you could include the line:<br />
<br />
<pre><br />
--Lsettings|@{selected|token_name}<br />
</pre><br />
<br />
To load all of the settings at once. By creating these setting sets for each character, you can specify a different color scheme for each character that can then be used in cards with a single formatting line.<br />
<br />
There is a supplemental ! command added to support saved settings:<br />
<br />
<pre><br />
!sc-liststoredsettings<br />
</pre><br />
<br />
Will produce a list of all stored setting names, with buttons to list the setting values stored in each group and a button to delete groups as needed.<br />
<br />
=== Visual Effects (--v) ===<br />
<br />
The --v statement can be used to create visual effects on the tabletop. The tag portion of the statement can be either "token" or "betweentokens". The content portion of the statement contains the required parameters for the effect generation, separated by spaces. If the effect is "none", no effect will be played. If any other value that doesn't match a Roll20 effect name will result in a burst-fire effect.<br />
<br />
For "token" effects, the parameters are the token id for the token the effect happens on, followed by the effect specifier.<br />
<br />
Example:<br />
<pre><br />
--vtoken|@{selected|token_id} burst-fire<br />
</pre><br />
<br />
For "betweentoken" effects, the parameters are the source token id, the target token id, and the effect specifier.<br />
<br />
Example:<br />
<pre><br />
--vbetweentokens|@{selected|token_id} @{target|token_id} beam-magic<br />
</pre><br />
<br />
'''''Version 1.2.8+'''''<br />
<br />
An additional effect specifier, "point" is available in 1.2.8+. This specifier allows you to create a visual effect at a designated X/Y pixel coordinate. Future updates will add custom-vfx support to this option. The parameters are the X and Y coordinates and the effect descriptor. As of version 1.2.9, you can also use custom effect specifiers with Point effects:<br />
<br />
<pre><br />
--vpoint|150 200 burst-fire<br />
</pre><br />
<br />
=== Echo to Chat (--e) ===<br />
<br />
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.<br />
<br />
Example:<br />
<pre><br />
--eThe Ghost|/em hovers around @{selected|character_name}... BOO!<br />
</pre><br />
<br />
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).<br />
<br />
'''''Whispering'''''<br />
<br />
You can use the echo statement to send a whisper, but there's a trick to it. If you execute this code here:<br />
<br />
<pre><br />
--eThe Ghost|/w ExamplePlayerName Boo.<br />
</pre><br />
<br />
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.<br />
<br />
So, in conclusion, it's best to use something like this when you're sending a whisper:<br />
<br />
<pre><br />
!script {{<br />
--#hidecard|1<br />
--&sender|The Ghost<br />
--&receiver|ExamplePlayerName<br />
--&message|Boo.<br />
--e[&sender]|/w [&receiver] [&message]<br />
--eScriptCards|/w gm **Whispered from [&sender] to [&receiver]:** [&message] <br />
}}<br />
</pre><br />
<br />
This will ensure that the message appears in your chat feed as well.<br />
<br />
=== Repeating Section Access (--R) ===<br />
<br />
ScriptCards (as of v0.0.13) supports accessing repeating section rows on a character sheet with the --R statement type. <br />
<br />
There are three basic commands you can use with --R, and they are specified by the tag used:<br />
<br />
<pre><br />
--Rfind|characterid;EntryName;SectionPrefix;SearchField<br />
</pre><br />
<br />
This is the most direct way to access a repeating section row. Supplying the character ID, followed by what you are looking for (Greatsword, for example), followed by the character sheet's section prefix (repeating_attack), followed by the field to check what you are searching for (atkname) will load the matching section (if found) into the script parsers memory. For example:<br />
<br />
<pre><br />
--Rfind|@{selected|character_id};Greatsword;repeating_attack;atkname<br />
</pre><br />
<br />
Will look at the character's "repeating_attack" section for an entry with an atkname value equal to "Greatsword". Similarly:<br />
<br />
<pre><br />
--Rfind|@{selected|character_id};Bite;repeating_npcaction;name<br />
</pre><br />
<br />
Will look for a "Bite" action on an NPC's action list.<br />
<br />
<pre><br />
--Rfirst|characterid;section prefix<br />
</pre><br />
<br />
This form of the --R command will look at all of the entries in the specified repeating section and load the first one into memory:<br />
<br />
<pre><br />
--Rfirst|@{selected|character_id};repeating_attack<br />
</pre><br />
<br />
Would load the character's first "repeating_attack" row into memory.<br />
<br />
<pre><br />
--Rnext|<br />
</pre><br />
<br />
No parameters are required for --Rnext, which loads the next entry in the list that was obtained with "first" into memory.<br />
<br />
However a row is obtained, it will be parsed to replace any attribute references (ie, @{level}) with the corresponding character attribute.<br />
<br />
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".<br />
<br />
You can reference repeating attribute data using the syntax [*R:attributename] syntax (similar to referencing standard character attributes).<br />
<br />
Here are some examples:<br />
<br />
Display the details of the "Greatsword" PC attack:<br />
<br />
<pre><br />
!script {{<br />
--Rfind|@{selected|character_id};Greatsword;repeating_attack;atkname<br />
--+Attack Name|[*R:atkname]<br />
--+Base Damage|[*R:dmgbase]<br />
}}<br />
</pre><br />
<br />
[[File:Scriptcards repeating greatsword.png|Repeating Greatsword Attack]]<br />
<br />
List all of the actions an NPC can take (just actions, not legendary, etc.)<br />
<br />
<pre><br />
!script {{<br />
--#title|NPC Actions<br />
--#leftsub|@{selected|token_name}<br />
--Rfirst|@{selected|character_id};repeating_npcaction<br />
--:DisplayLoop|<br />
--?"[*R:name]" -eq NoRepeatingAttributeLoaded|Done<br />
--+Action:|[*R:name] [*R:attack_damage] [*R:attack_damagetype]<br />
--?"[*R:attack_damage2]" -eq ""|NoSecondaryDamage<br />
--+ |[*R:attack_damage2] [*R:attack_damagetype2]<br />
--:NoSecondaryDamage|<br />
--Rnext|<br />
-->DisplayLoop| <br />
--:Done|<br />
}}<br />
</pre><br />
<br />
[[File:Scriptcards repeating npcactions.png]]<br />
<br />
In the script above, we get the "first" repeating_npcaction and display information about it. We then execute "next" and repeat until we run into "NoRepeatingAttributeLoaded".<br />
<br />
'''''Special debugging command: dump'''''<br />
<pre><br />
--Rdump|<br />
</pre><br />
<br />
The "dump" command will list all of the attributes ScriptCards knows about for the currently loaded repeating row to the API Console Log.<br />
<br />
=== Assign Variable to Built-In Function (--~) ===<br />
<br />
ScriptCards has the ability to run a function built into the API script and return the results to a variable. Some functions return roll variables, while others return strings. See the function table below for details. The format is:<br />
<br />
--~VariableName|function;param1;param2;param3;...<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Function Name !! Parameters !! Description<br />
|-<br />
| distance || token_A_ID;token_B_ID || Calculate the Chebyshev distance in grid units between two tokens. This is the measurement scheme D&D 4E/5E use for diagonal distance measurement<br />
|-<br />
| euclideandistance || token_A_ID;token_B_ID || Calculate the Euclidean distance between two tokens. This is essentially the Pythagorean theorem in action. Returns the result in grid units.<br />
|-<br />
| euclideanpixel || token_A_ID;token_B_ID || Calculate the Euclidean distance between two tokens and returns the result is pixels instead of grid units. <br />
|-<br />
| euclideanlong || token_A_ID;token_B_ID || 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 is calculated instead of before. More accurate over long distances. <br />
|-<br />
| manhattandistance || token_A_ID;token_B_ID || Also called "taxicabdistance" (which is an acceptable function name), this measures to how-many-over, how-many-up/down distance, disallowing diagonal movement.<br />
|-<br />
| getselected || none || 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 the first selected token, VariableName2 the second, etc.<br />
|}<br />
<br />
'''''Functions with Sub Functions'''''<br />
<br />
Most ScriptCards functions are grouped into set as sub functions. The table below lists the major functions and their sub functions.<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Function Name !! Sub Function !! Parameters !! Return Type !! Description<br />
|-<br />
| array || define || arrayname;value1;value2;... || none || Creates an array called "arrayname" and adds value1, value2, etc. to the array<br />
|-<br />
| array || sort || arrayname || none || Sorts the specified array in place in ascending order<br />
|-<br />
| array || add || arrayname;value1;value2;... || none || Adds value1, value2, ... to the existing array "arrayname"<br />
|-<br />
| array || remove || arrayname;value1;value2;... || none || Removes value1, value2, ... from the existing array "arrayname". Resets the array index to 0.<br />
|-<br />
| array || replace || arrayname;currentvalue;newvalue || none || Replaces all occurrences of "currentvalue" in "arayname" with "newvalue"<br />
|-<br />
| array || setatindex || arrayname;index;newvalue || none || Replaces the array item at index "index" with "newvalue"<br />
|-<br />
| array || getindex || arrayname || stringVariable || Retrieves the current index in "arrayname" and stores it in the supplied string variable<br />
|-<br />
| array || setindex || arrayname;newindex || none || Sets the current index in array "arrayname" to "newindex"<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| array || removeat || arrayname;indexposition || none || Removes the item at index "indexposition" from "arrayname". Resets the current array index to 0.<br />
|-<br />
| array || indexof || arrayname;searchvalue || stringVariable || Searches the array "arrayname" for and item with the value of "searchvalue" and, if found, returns the index of the first matching value or "ArrayError" if not found<br />
|-<br />
| array || getlength || arrayname || stringVariable || Returns the number of items in array "arrayname"<br />
|-<br />
| array || pagetokens || arrayname;tokenid;(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. 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.)<br />
|-<br />
| 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.<br />
|-<br />
| array || stringify || arrayname || stringVariable || Returns all of the items in "arrayname" as a string separated by semicolons (;)<br />
|-<br />
| array || fromstring || arrayname || delimiter;string || Creates an array from "string", splitting "string" on "delimiter" to separate the items<br />
|-<br />
| array || statusmarkers|| arrayname;tokenid || none|| Creates an array (arrayname) of the active statusmarkers (sometimes called Token Markers) for the specified tokenid<br />
|-<br />
| math || angle || math;angle;tokenid;tokenid|| rollVariable || Calculates the angle between two tokens and returns the value in degrees<br />
|-<br />
| math || ceil || math;ceil;value || rollVariable || Rounds '''value''' up to the next integer, dropping any decimal portion of the number<br />
|-<br />
| math || clamp || math;clamp;value;lowerBound;upperBound || rollVariable || Returns '''value''', but restricted to the range of '''loweBound''' and '''upperBound'''.<br />
|-<br />
| math || floor || math;floor;value || rollVariable || Rounds '''value''' down, dropping any decimal portion of the number<br />
|-<br />
| math || max || math;max;valueA;valueB || rollVariable || Returns the larger of '''valueA''' vs '''valueB'''<br />
|-<br />
| math || min || math;min;valueA;valueB || rollVariable || Returns the smaller of '''valueA''' vs '''valueB'''<br />
|-<br />
| math || round || math;round;value || rollVariable || Rounds '''value''' to the nearest integer<br />
|-<br />
| string || length || string;length;stringValue || rollVariable || Returns the length of '''stringValue''' in characters<br />
|-<br />
| string || before || string;before;searchText;stringValue || stringVariable || Searches '''stringValue''' for '''searchText''' and returns the portion of '''stringValue''' prior to that text<br />
|-<br />
| string || after || string;after;searchText;stringValue || stringVariable || Searches '''stringValue''' for '''searchText''' and returns the portion of '''stringValue''' after that text<br />
|-<br />
| string || left || string;left;count;stringValue || stringVariable || Returns the leftmost '''count''' characters of '''stringValue'''<br />
|-<br />
| string || right || string;right;count;stringValue || stringVariable || Returns the rightmost '''count''' characters of '''stringValue'''<br />
|-<br />
| string || replace || string;replace;searchText;replaceText;stringValue || stringVariable || Replaces '''searchText''' in '''stringValue''' with '''replaceText''' and returns the resulting string<br />
|-<br />
| string || replaceall || string;replace;searchText;replaceText;stringValue || stringVariable || Replaces all intances of '''searchText''' in '''stringValue''' with '''replaceText''' and returns the resulting string '''''Requires 1.2.9+'''''<br />
|-<br />
| string || trim || string;trim;stringValue || stringVariable || Removes leading and trailing spaces from stringValue and returns the result. <br />
|-<br />
| string || substring || string;substring;start;count;stringValue || stringVariable || Returns '''count''' characters starting at '''start''' from '''stringValue'''<br />
|-<br />
| 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.<br />
|-<br />
| string || tolowercase || string;tolowercase;stringValue || stringVariable || Converts the passed string to lower case and assigns to the passed variable name. <br />
|-<br />
| string || touppercase || string || stringVariable || Converts the passed string to upper case and assigns to the passed variable name. <br />
|-<br />
| 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. <br />
|-<br />
| 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.<br />
|-<br />
| 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'''.<br />
|-<br />
| turnorder || clear || none || none || Clears all entries from the {{Turn Tracker}}/Initiative<br />
|-<br />
| turnorder || addtoken || tokenid;trackervalue || none || Adds the token represented by "tokenid" to the initiative tracker with an initiavie value of "trackervalue"<br />
|-<br />
| turnorder || replacetoken || tokenid;trackervalue || none || Replaces the token represented by "tokenid" in the initiative tracker with an initiavie value of "trackervalue". Will add the token if it doesn't exist in the tracker.<br />
|-<br />
| turnorder || removetoken || tokenid || none || Removes the token represented by "tokenid" from the initiative tracker if it exists<br />
|-<br />
| turnorder || addcustom || textlabel;trackervalue || none || Add a custom text entry to the {{Turn Tracker}}/Initiative named "textlabel" with an initiative value of "trackervalue"<br />
|-<br />
| system || date || getdatetime || stringVariable || Returns the date time in the active timezone (see settings) <br />
|-<br />
| system || date || getdate || stringVariable || Returns the date in the active timezone (see settings) <br />
|-<br />
| system || date || gettime || stringVariable || Returns the time in the active timezone (see settings)<br />
|-<br />
| system || dumpvariables || "rolls", "string", or "array" || none || Dumps all of the defined variables of the indicated type to the console log<br />
|-<br />
| system || findability || system;findability;charactername;abilityname || stringVariable || Returns the object ID of the ability on the indicated character or "AbilityNotFound"<br />
|-<br />
|}<br />
<br />
Examples:<br />
<br />
<pre><br />
--~HowFarAway|distance;@{selected|token_id};@{target|token_id}<br />
</pre><br />
<br />
Returns the distance (Chebyshev) between the selected and target tokens and stores it in "HowFarAway".<br />
<br />
<pre><br />
--SelectedDudes|getselected<br />
</pre><br />
<br />
If 5 tokens were selected, 6 variables would be created: SelectedDudesCount (with a value of 5), SelectedDudes1, SelectedDudes2, SelectedDudes3, SelectedDudes4, SelectedDudes5.<br />
<br />
=== Information Request (--i) ===<br />
<br />
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.<br />
<br />
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.<br />
<br />
After the user has clicked the button and responded to the requests, ScriptCards will resume processing the script from where it left off.<br />
<br />
Here is an example “i” line:<br />
<br />
<pre><br />
--IScriptCards needs additional information to continue;Click to select a target and provide information|t;MyNewTarget;Missile1Target||q;MyNameIs;What is your name?<br />
</pre><br />
<br />
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.<br />
<br />
Supported information request types are “t” for target token, and “q” for query.<br />
<br />
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).<br />
<br />
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:<br />
<br />
<pre><br />
q;UserName;What is your name?|Fred|Bob|Sally|Nancy<br />
</pre><br />
<br />
Would have a dropdown menu with four choices.<br />
<br />
== Inline Formatting ==<br />
<br />
Inline formatting is processed on Direct Output lines only (--+ lines) and the following inline format markup is available:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Formatting Tags !! Description<br />
|-<br />
| [b]..[/b] || Bold the text between the markers <br />
|-<br />
| [i]..[/i] || Italicize the text between the markers <br />
|-<br />
| [u]..[/u] || Underline the text between the markers <br />
|-<br />
| [s]..[/s] || Strike-Thru the text between the markers <br />
|-<br />
| [c]..[/c] || Center alignment <br />
|-<br />
| [l]..[/l] || Left alignment <br />
|-<br />
| [r]..[/r] || Right alignment <br />
|-<br />
| [j]..[/j] || Full justification alignment <br />
|-<br />
| [#xxx]..[/#] or [#xxxxxx]..[/#] || Use a 3 or 6 digit hex code to colorize the text between the markers <br />
|-<br />
| [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, <code>[img width=128 height=128]</code> )<br />
|-<br />
| [button]caption::action[/button] || Create a button with the label "caption" that performs the action defined by "action". <br />
|-<br />
| [t] || Converted to HTML table tag. Text after the "t" will be included inside the tag (width, border, etc)<br />
|-<br />
| [/t] || Converted to HTML close table tag.<br />
|-<br />
| [tr] || Converted to HTML table row tag. Text after the "tr" will be included inside the tag<br />
|-<br />
| [/tr] || Converted to HTML close table row tag.<br />
|-<br />
| [td] || Converted to HTML table cell tag. Text after the "tr" will be included inside the tag<br />
|-<br />
| [/td] || Converted to HTML close table cell tag.<br />
|}<br />
<br />
== Variables ==<br />
<br />
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. While it is possible to assign both a string and a roll variable the same name, doing so will likely result in confusion when looking at the script later, so it is not recommended.<br />
<br />
String Variables are assigned with the --& statement and are referenced using [&variableName] notation.<br />
<br />
Roll Variables are assigned with the --= statement, and the assignment value is always processed by the ScriptCards Roll Processor (resolves dice rolls, etc.)<br />
<br />
There are a handful of variables assigned automatically when a ScriptCard is executed. These are all string variables, and are:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Variable !! Value<br />
|-<br />
| SendingPlayerID || Contains the object ID of the player that sent the macro<br />
|-<br />
| SendingPlayerName || Contains the display name of the player<br />
|-<br />
| SendingPlayerColor || Contains the color code associated with the player<br />
|-<br />
| SendingPlayerSpeakingAs || The contents of the "Speaking As" dropdown window<br />
|-<br />
| SendingPlayerIsGM || Contains 1 if the player is a GM, and 0 if the player is NOT a GM<br />
|}<br />
<br />
== Arrays ==<br />
<br />
Arrays are a special type of variable, and are managed by the function (<nowiki>--~</nowiki> command). All of the array function commands follow the same pattern:<br />
<br />
<pre>--~variableName|array;subcommand;arrayname;param1;param2;param3;...</pre><br />
<br />
Not all array commands return anything to "variableName". The function table above will specify the return type of the command if any.<br />
<br />
There are a couple of different ways to create an array:<br />
<br />
The '''define''' array subcommand creates (or recreates) an array and assigns it values - one for each included parameter after the array name. For example:<br />
<br />
<pre>--~|array;define;Fruits;mango;peach;strawberry;apricot;banana;apple</pre><br />
<br />
will create an array called '''Fruits''' with 6 elements in the order listed in the command (mango, peach, etc.)<br />
<br />
You can also use two other subcommands to create arrays based on tokens:<br />
<br />
<pre>--~Count|array;pagetokens;Everybondy;@{selected|token_id}</pre><br />
<br />
and<br />
<br />
<pre>--~Count|array;selectedtokens;Selected</pre><br />
<br />
In both cases, arrays of tokens will be created, and a string variable called "Count" will be set to the number of tokens in the array. The '''pagetokens''' command returns (by default) all of the tokens on the page that contains the token passed as the parameter after the array name. You can filter the tokens that "pagetokens" includes in the array by appending an optional parameter describing the type of token you are looking for:<br />
<br />
<pre>--~Count|array;pagetokens;Everybondy;@{selected|token_id};npc</pre><br />
<br />
Will return only tokens on the page that represent characters that do not have a ''controlledby'' parameter set. The available options are "all" (default), "char", "graphic", "pc", and "npc".<br />
<br />
The '''selectedtokens''' command returns an array with all of the tokens that were selected when the script was called.<br />
<br />
You can also use an arbitrary string to create an array, specifying a delimiter with the '''fromstring''' command:<br />
<br />
<pre><br />
--&names|Fred<br />
--&names|+,Sally<br />
--&names|+,Ted<br />
--&names|+,Joyce<br />
--~|array;fromstring;,;[&names]<br />
</pre><br />
<br />
The above example builds a comma-separated string and then uses "fromstring" to create an array with 4 elements from it, specifying the comma as the delimiter.<br />
<br />
Finally, you can use the '''statusmarkers''' command to create an array with one entry for each active status marker on a specified token:<br />
<br />
<pre>--~|array;statusmarkers;Conditions;@{selected|token_id}</pre><br />
<br />
will create an array with one entry for each status active on the selected token. The array elements will be the internal name of the status (if you are using custom status marker packs, the names will be specified in the marker pack).<br />
<br />
'''Traversing Arrays'''<br />
<br />
Each array keeps track of an internal index position (starting at 0). Several commands let you manage this index:<br />
<br />
*'''getindex''' returns the current index value<br />
*'''setindex''' sets the index to the specified location in the array<br />
*'''getlength''' returns the number of elements in the array<br />
*'''indexof''' returns the index location of the specified element<br />
<br />
Other commands let you retrieve values from the array:<br />
<br />
*'''getfirst''' sets the index to 0 and returns the value at that position<br />
*'''getnext''' advances the index by 1 and returns the new current value<br />
*'''getprevious''' reduces the index by 1 and returns the new current value<br />
*'''getlast''' sets the index to the last elements in the array and returns the new current value<br />
<br />
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.<br />
<br />
'''Manipulating Array Elements'''<br />
<br />
Several array commands deal with inserting, removing, and modifying elements:<br />
<br />
*'''add''' works just like define, except that it takes an existing array and adds elements to it based on the passed parameters<br />
*'''remove''' looks for items matching each passed parameter and removes them from the indicated array if they exist<br />
*'''removeat''' allows you to specify an index location in the array and remove the element at that position<br />
*'''replace''' searches an array for a value and replaces all occurrences of it with a new value (if found)<br />
*'''sort''' sorts the elements in the array in ascending order<br />
*'''strinfigy''' returns a string variable that includes each array element separated by semicolons (;) <br />
<br />
'''Referencing Array Elements'''<br />
<br />
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.<br />
<br />
<pre><br />
!script {{<br />
--~dummy|array;pagetokens;myarray;@{selected|token_id}<br />
--~count|array;getcount;myarray<br />
--+Total:|There are [&count] graphical objects on the page<br />
--~testvar|array;getfirst;myarray<br />
--:loop|<br />
--+Value|[*[&testvar]:character_name]<br />
--~testvar|array;getnext;myarray<br />
--?[&testvar] -ne ArrayError|loop<br />
--+Loop1|Is Done!<br />
}}<br />
</pre><br />
<br />
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:<br />
<br />
<pre><br />
!script {{<br />
--~dummy|array;pagetokens;myarray;@{selected|token_id}<br />
--~count|array;getcount;myarray<br />
--+Total:|There are [&count] graphical objects on the page<br />
--%loopCounter|1;[&count]<br />
--+Value|[*[@myarray([&loopCounter])]:character_name]<br />
--%|<br />
--+Loop|Is Done!<br />
}}<br />
</pre><br />
<br />
This line : <nowiki>--+Value|[*[@myarray([&loopCounter])]:character_name]</nowiki> uses [@arrayName(index)] format (inside a [*characterid:attribute] syntax) to perform the same task as running through the loop with the index.<br />
<br />
(Note: Additional examples are on the way...)<br />
<br />
== For...Next Loops ==<br />
<br />
For...Next loops in ScriptCards are supported with the with the --% statement type. A loop is defined by starting off with:<br />
<br />
<pre><br />
--%LoopCounter|<start>;<end>;[step]<br />
</pre><br />
<br />
The start and end values are required, while the step parameter is optional. If the step is omitted, it will be assumed to be 1. A string variable named after the line tag ("LoopCounter" in the case above) will be created and will hold the current iteration value for the loop. Here is a real example:<br />
<br />
<pre><br />
--%LoopCounter|1;10;1<br />
</pre><br />
<br />
This will begin a loop identified by "LoopCounter" that will start at 1, increasing by 1 each iteration (the step) until it has completed 10 executions.<br />
<br />
The "next" statement is simply <code>--%|</code>, with no tag or parameters. This indicates to ScriptCards that it should increment the counter and go back to the beginning of the loop. Extending the example above:<br />
<br />
<pre><br />
!script {{<br />
--%LoopCounter|1;10;1<br />
--=Roll|1d20<br />
--+Loop|Counter is [&LoopCounter], roll was [$Roll]<br />
--%|<br />
}}<br />
</pre><br />
<br />
The <code>--%!|</code> sequence will break out of the loop, no matter how many iterations are remaining.<br />
<br />
The % and %! character sequences can also be used as part of a 1.2.1+ non-branching conditional to continue or break the loop:<br />
<br />
<pre><br />
--?"X[&RollInto]X" -eq "XX"|%<br />
</pre><br />
<br />
In this example, if the string variable RollInfo is empty, the loop will return to the top and continue with the next iteration, while:<br />
<br />
<pre><br />
--?"X[&RollInto]X" -eq "XX"|%!<br />
</pre><br />
<br />
Would cause the whole loop to end if the condition were true.<br />
<br />
== Referencing ==<br />
<br />
=== Roll Variables===<br />
<br />
Roll Variables can be referenced from the content portion of any line type, and from the tag portion of conditional statements. The referenced value is replaced when the line is executed.<br />
<br />
There are several modifiers that can be used to reference parts of a roll:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Modifier !! Meaning<br />
|-<br />
| No modifier || In a Direct Output Line (<nowiki>--+</nowiki>), GM Output Line (<nowiki>--*</nowiki>), or String Assignement (<nowiki>--&</nowiki>), 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<br />
|-<br />
| .Total || The end result of the roll equation. Formatting rules for "No Modifier" apply based on line type. <br />
|-<br />
| .Raw || The total value of the roll variable without any formatting, no matter what kind of line the reference is used in.<br />
|-<br />
| .Base || The cumulative result of any dice rolled in the Roll Text (Numeric modifiers are not included) <br />
|-<br />
| .Ones || The number of dice in the roll that came up as 1s <br />
|-<br />
| .Aces || The number of dice in the roll that came up as the maximum number on the die <br />
|-<br />
| .Odds || The number of dice in the roll that came up with an odd number <br />
|-<br />
| .Evens || The number of dice in the roll that came up with an even number <br />
|-<br />
| .RollText || The raw text of the roll that was use to generate the results <br />
|-<br />
| .Text || A text representation of the results of the roll, including the numbers rolled for each die <br />
|-<br />
| .tableEntryText || The text portion of the result of a table roll<br />
|-<br />
| .tableEntryImgURL || The image source portion of the result of a table roll<br />
|-<br />
| .tableEntryValue || If the tableEntryText is purely numeric, will contain the numeric value<br />
|}<br />
<br />
=== String Variables ===<br />
<br />
To reference a string variable, use the notation [&variablename]. String variables can be referenced in direct output, roll variable assignment, and string variable assignment statements.<br />
<br />
=== Character/Token Attributes ===<br />
<br />
A character or token attribute can be referenced from content portion of any type of line and is substituted when the line is executed. The general format for referencing a character attribute is [*ID:attribute]. ID can be a token ID or a character ID (these start with a dash). Additionally if you have specified a sourceToken or targetToken, you can substitute "S" or "T" for the ID (for example [*S:npc_type] will retrieve the npc_type attribute from the source token.<br />
<br />
By default, all attribute references will be pulled from the '''''character''''' object that the ID represents (either directly or by being a Token ID that represents a character).<br />
<br />
Keep in mind, that if you want to access the "max" of a character attribute (for example, the max hit points), then you cannot trust the name that your roll20 character sheet shows you when you hover your mouse over the max hit points. For example, this reference will not work: [*S:hp_max]. Instead, you need to use this reference: [*S:hp^].<br />
<br />
If your ID refers to a token, token attributes can be accessed by preceding the attribute name with "t-", for example [*S:t-aura1_radius]. Supported token attributes are:<br />
<br />
{|<br />
| t-name || t-id || t-statusmarkers || t-bar1_value<br />
|-<br />
| t-bar1_max || t-bar2_value || t-bar2_max || t-bar3_value<br />
|-<br />
| t-bar3_max || t-top || t-left || t-width<br />
|-<br />
| t-height || t-rotation || t-layer || t-aura1_radius<br />
|-<br />
| t-aura1_color || t-aura2_radius || t-aura2_color || t-aura1_square<br />
|-<br />
| t-aura2_square || t-tint_color || t-light_radius || t-light_dimradius<br />
|-<br />
| t-light_angle || t-light_losangle || t-light_multiplier || t-light_otherplayers<br />
|-<br />
| t-light_hassight || t-flipv || t-fliph || t-controlledby<br />
|-<br />
| t-_cardid || t-_pageid || t-imgsrc || t-bar1_link<br />
|-<br />
| t-bar2_link || t-bar3_link || t-represents || t-layer<br />
|-<br />
| t-isdrawing || t-name || t-gmnotes || t-showname<br />
|-<br />
| t-showplayers_name || t-showplayers_bar1 || t-showplayers_bar2 || t-showplayers_bar3<br />
|-<br />
| t-showplayers_aura1 || t-showplayers_aura2 || t-playersedit_name || t-playersedit_bar1<br />
|-<br />
| t-playersedit_bar2 || t-playersedit_bar3 || t-playersedit_aura1 || t-playersedit_aura2<br />
|-<br />
| t-lastmove || t-adv_fow_view_distance || t-has_bright_light_vision || t-has_night_vision<br />
|-<br />
| t-night_vision_distance || t-emits_bright_light || t-bright_light_distance || t-emits_low_light<br />
|-<br />
| t-low_light_distance || t-has_limit_field_of_vision || t-limit_field_of_vision_center || t-limit_field_of_vision_total<br />
|-<br />
| t-has_limit_field_of_night_vision || t-limit_field_of_night_vision_center || t-limit_field_of_night_vision_total || t-has_directional_bright_light<br />
|-<br />
| t-directional_bright_light_center || t-directional_bright_light_total || t-has_directional_dim_light || t-directional_dim_light_center<br />
|-<br />
| t-directional_dim_light_total || t-lightColor || || |<br />
|}<br />
<br />
'''''It is important to note that some attributes names on tokens have corresponding attribute names on characters, which represent different values. For example, [*T:id] returns the character ID, while [*T:t-id] returns the token ID.'''''<br />
<br />
=== Subroutine Parameters ===<br />
<br />
When using a gosub statement (-->) or a conditional marked as a gosub (prefixing the label with a > character), you can pass any number of parameters separated by semicolons (;) that the code in the subroutine can utilize.<br />
<br />
Subroutine parameters are numbered starting at 1, and are accessed by using the notation [%number%], so the first parameter is [%1%], the second is [%2%], etc.<br />
<br />
Parameter substitution happens on all line types, and happens prior to character attribute references or roll variable substitution.<br />
<br />
=== Campaign Attribute ===<br />
You can retrieve properties of the API's Campaign object with the [*C:attributename] syntax. For example, [*C:playerpageid] will retrieve the current player ribbon page from the Campaign object.<br />
<br />
=== Page Attributes ===<br />
If you have set the '''activepage''' parameter, you can retrieve page-related properties with the [*P:attributename] syntax, including the page's UDL parameters.<br />
<br />
=== Repeating Section Values ===<br />
<br />
You can reference repeating attribute data using the syntax [*R:attributename] syntax (similar to referencing standard character attributes). The currently active repeating row information will be used to retrieve attribute values. You can also retrieve the full attribute name for a repeating row attribute by using the [*R>attributename] notation. This is useful to pass to things like chatsetattr.<br />
<br />
=== Array Elements ===<br />
After an array has been declared, the elements can be referenced with [@arrayName(index)]. Array indices start at 0.<br />
<br />
== Deferred Resolution for Meta Scripts ==<br />
<br />
As of 1.2.9, ScriptCards supports a deferral character for use when calling another API script with via the --@ statement, to defer processing of meta script references so they get processed prior to the sub-API call insted of prior to ScriptCards execution. To defer this processing for meta script (SelectManager, Fetch) by inserting a deferral character into the meta call. For example, if I want to have ScriptCards call TokenMod as if the token for "Quej Gr'stra" (yes, I let Roll20 name my test NPCs) I could use something like this:<br />
<br />
--@token-mod|{^& select Quej Gr'stra} _on showname<br />
<br />
The "^" in between { and & will prevent SelectManager from seeing the call when the ScriptCard script is processed, but the --@ statement will remove the deferral character so the command that will be sent by ScriptCards is:<br />
<br />
!token-mod {& select Quej Gr'stra} --on showname<br />
<br />
With the deferral character removed, SelectManager will see the {& select ...} and do its magic.<br />
<br />
While the default deferral character is "^", the deferral character is a setting that can be changed:<br />
<br />
--#deferralcharacter|%<br />
<br />
Will make % the deferral character for future --@ statements in the running script.<br />
<br />
There are currently three supported Meta script structures: {^&...} for SelectManager, @^(...) and *^(...) for fetch, where the ^ in the structures here represents the placement of the deferral character.<br />
<br />
== Arrays ==<br />
<br />
Arrays are a new data type introduced in version 1.1.12 of ScriptCards, and are manipulated with associated function (--~) commands.<br />
<br />
* Arrays are a lists of strings. Items in an array cannot contain the semi-colon (;) character, as that is used to separate parameters in the function code that deals with arrays.<br />
* Arrays are accessed via the --~ script command. In some cases, the value of the tag (variable name) for array commands is not used, and can be a dummy value or simply omitted. I have omitted them in the statements below.<br />
* All commands that DO return a value return string values, even if the content is numeric.<br />
* If a command returns a value and there is some sort of reason that it isn't an array value, you will get "ArrayError" in the return value. This can happen if you reach the end of an array while stepping through it, for example, so checking for "ArrayError" can serve as the end condition for a loop.<br />
* Each array keeps track of its current index, allowing you to step forward and backwards through arrays.<br />
* Any number of arrays can be defined.<br />
* Unlike string variables and roll variables, array variables cannot (currently) be referenced directly. It is necessary to use the function (--~) syntax to manipulate arrays and get values from them as strings for use in other parts of your script.<br />
<br />
<br />
== Reentrant Scripts ==<br />
<br />
Reentrant scripts allow you to create buttons in your script code that will re-execute the script at a given label within the code. If you set the reentrant setting (--#reentrant|somevalue) to a non-zero value, your setting and variable information will be preserved between executions. Reentrant script can be used to present menus or choices and then continue acting.<br />
<br />
Reentrant buttons are created with the [rbutton]Caption::ReentryLabel;Parameter[/rbutton] construct. The caption will be displayed on the generated button. ReentryLabel is the name of a label in your script that the button will jump to when clicked, and Parameter will be passed in as a string value called "reentryval".<br />
<br />
Example:<br />
<pre><br />
!script {{<br />
--#reentrant|testing<br />
--=Roll|1d20<br />
--+Roll|[$Roll]<br />
--&String|That was a [$Roll.Raw]!<br />
--~x|array;define;MyArray;Apple;Banana;Orange<br />
--+Try it|[rbutton]Hello!::EXEC_PC_SPELL;9[/rbutton]<br />
--X|<br />
<br />
--:EXEC_PC_SPELL|<br />
--+ReentryVal|[&reentryval]<br />
--+The value of Roll is|[$Roll]<br />
--+Value of String|[&String]<br />
--+Array|[@MyArray(0)]<br />
--X|<br />
}}<br />
</pre><br />
<br />
This script sets up some variables and then displays a button labeled "Hello!". If the user clicks the button, the script will be re-entered starting at the "EXEC_PC_SPELL", which will display the content of the variables from the original execution.<br />
<br />
'''''Note: This section needs to be expanded upon'''''<br />
<br />
== Procedure Libraries ==<br />
<br />
You can now create handouts in your game in Roll 20 with the name format "ScriptCards Library NAME", where name is a name you assign to the library. Library names are case sensitive. It is my hope that the more proficient ScriptCards scripters out there will provide procedure libraries (or procedures that can be included in libraries) for others to use to make their scripting life easier. Be they specific to a game system, or to a type of activity, I think a robust set of libraries that GMs could use to enhance their scripting capabilities would be very valuable to the community. Should such things begin to emerge, I’ll create a portion of the ScriptCards Wiki page to house them.<br />
<br />
To include one or more libraries in a script, use the +++libname+++ directive (does not need a -- line associated with it). Multiple library names can be specified by separating them with semicolons (i.e., +++General;dnd5elib;Colorize+++ would include three libraries (General, dnd5elib, and Colorize).<br />
<br />
Included libraries are separated from the main script code by the automatic inclusion of "--X|" before the first library is appended to the script, and all libraries are loaded at the end of the script before script processing takes place.<br />
<br />
Procedures and labels in libraries can be used just as if they were included in the body of your script. Note that this DOES mean that you could, technically, jump into a library with a direct branch (--^) or direct branch conditional, but I recommend using libraries to store reusable procedures.<br />
The Notes section of the library handout stores the library code, and is written just like any other ScriptCards code except:<br />
<br />
* They cannot use roll queries (?{Some Prompt:}) to get information from the user at execution time.<br />
* They cannot use @{} notation to access character and token information.<br />
<br />
Both of these limitation stem from the fact that Procedure Libraries are not processed by the chat server, which is what handles these items.<br />
<br />
Here is an example of handling damage modifications (resistance, vulnerability, and immunity) in D&D 5E with a library:<br />
<br />
<pre><br />
!script {{<br />
+++dnd5elib+++<br />
--#|Damage Modifiers Test<br />
--#targettoken|@{target|token_id}<br />
-->Lib5E_CheckDamageModifiers|ResistType;fire<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] fire damage<br />
<br />
-->Lib5E_CheckDamageModifiers|ResistType;cold<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] cold damage<br />
<br />
-->Lib5E_CheckDamageModifiers|ResistType;poison<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] poison damage<br />
<br />
-->Lib5E_CheckDamageModifiers|ResistType;acid<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] acid damage<br />
<br />
--X|<br />
}}<br />
</pre><br />
<br />
Library content (In a handout called “ScriptCards Library dnd5elib” NOTE: Paste into Notepad first and then paste into the handout in Roll20 to avoid bringing over HTML formatting from the web site):<br />
<br />
<pre><br />
--/|ScriptCards Library: dnd5elib version 0.0.1<br />
--/|Provides various utility procedures for D&D 5E games<br />
<br />
--/|Lib5E_CheckDamageModifiers handle damage resistance, vulnerability, and immunity. <br />
--/|Pass a string variable to be filled with a string to be appended to a dice roll and the damage type <br />
<br />
--:Lib5E_CheckDamageModifiers|damageVariableName;damageType<br />
--&[%1%]|<br />
--?"[*T:npc_vulnerabilities]" -inc "[%2%]"|>_Lib5E_IsVulnerable;[%1%]<br />
--?"[*T:npc_resistances]" -inc "[%2%]"|>_Lib5E_IsResistant;[%1%]<br />
--?"[*T:npc_immunities]" -inc "[%2%]"|>_Lib5E_IsImmune;[%1%]<br />
--<|<br />
<br />
--:_Lib5E_IsVulnerable| --&[%1%]| * 2 [Vulnerable] --<|<br />
--:_Lib5E_IsResistant| --&[%1%]| \ 2 [Resistant] --<|<br />
--:_Lib5E_IsImmune| --&[%1%]| * 0 [Immune] --<|<br />
</pre><br />
<br />
The idea is that the functions in the library create a string that can be appended to a roll to modify the output based on resistances, so you pass Lib5E_CheckDamageModifiers the name of the string variable you want to use and the damage type. The variable (ResistType in this case) will include either nothing, “* 2 [Vulnerable]”, “\ 2 [Resistant]”, or “* 0 [Immune]” which can be included in a roll assignment (--=) to modify the damage as appropriate. The order here might be important if an NPC is misconfigured to be both resistant and immune to the same damage type. Since immune is an absolute, having it last ensures that it will override resistant or vulnerable. A creature that is both vulnerable and resistant (again, misconfigured) will come back as resistant since that condition is checked after vulnerable.<br />
Some notes: I prefix my library labels with either “Lib5E_” or “_Lib5E_” as a clarity convention. This isn’t strictly necessary but you should be aware that if two libraries (or if your script and a library) define the same label, the last label defined will win. Since libraries are appended to the end of the script in the order you include them in the +++libname+++ directive, you can somewhat control this, but it is probably best to avoid re-declaring labels. <br />
<br />
In my case, items beginning with “Lib5E_” are intended to be called by scripts, while items beginning with “_Lib5E_” are intended to be used as subroutines by the “public” procedures. Of course, there is no reason you couldn’t call them directly.<br />
<br />
You might also note that I’ve included some library information in comment lines (--/|) at the top of the library. These are ignored by ScriptCards, and are a good way to convey requirements, parameters, usage information, etc.<br />
<br />
== Example Libraries ==<br />
<br />
=== dnd5elib ===<br />
<br />
[https://github.com/kjaegers/ScriptCards Download the dnd5elib Library from the ScriptCards GitHub]<br />
<br />
The '''dnd5elib''' library provides a collection of utility procedures that help simplify dealing with the D&D 5E Official Sheet. Some of the procedures in this library require '''chatsetattr''' to be installed in your game. This is a growing library, and currently only has a handful of routines. They are:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Procedure Name !! Notes<br />
|-<br />
| style="white-space:nowrap" | Lib5E_CheckDamageModifiers || This procedure can be used to evaluate vulnerabilities, resistances, and invulnerabilities on an NPC. After setting the --#target| parameters, pass the Lib5E_CheckDamageModifiers procedure a variable name (no reference information) and a damage type (i.e., fire, cold, bludgeoning, etc.) and a string variable with the name passed in as the first parameter will be created that contains text that can be included in a roll line (--=) in order to modify the roll as appropriate. For example, '''-->Lib5E_CheckDamageModifiers|ResistType;fire''' will check the current target character's attributes for "fire" and will either return an empty string (no references), "* 0 [Immune]" if the creature is immune, "\ 2 [Resistant]" if the creature is resistant, or "* 2 [Vulnerable]" if the creature is vulnerable to fire damage.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_DeductSpellSlot || Pass in a character_id and a slot level, and the script will expend one spell slot of that level, capping the value at 0 slots remaining. For Example '''<nowiki>-->Lib5E_DeductSpellSlot|@{selected|character_id};1</nowiki>''' to deduct a first level spell slot from the selected character.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_FindResource || Used to locate a resource value on a character. Pass in a character_id, a resource name, and two variable names. The procedure will check both repeating and non-repeating resources looking for a resource whose name matches what was passed in and return three variables. The first will be a string variable named for the 3rd parameter and contains the attribute name of the resource's "name" field. The second will be a string variable named after parameter 4 and contains the resource's value field attribute name, and the third variable is a Roll Variable, also named after the 4th parameter that contains the current resource value. Example: '''<nowiki>-->Lib5E_FindResource|@{selected|character_id};Crossbow bolts;ResName;ResValue</nowiki>''' will find "Crossbow bolts" as a resource on the character and return [&ResName] which is the name of the resource attribute, [&ResValue] which is the '''name of the attribute that stores the value''' and [$ResValue] which is the current numeric value of the resource.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Global_Attack_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Attack Modifiers (repeating_tohitmod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Bless" for 1d4 active and "Being Cool" for +2 active, I will get a return string " + 1d4 [Bless] + 2 [Being Cool]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Save_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Save Modifiers (repeating_savemod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Bless" for 1d4 active and "Being Cool" for +2 active, I will get a return string " + 1d4 [Bless] + 2 [Being Cool]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Skill_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Skill Modifiers (repeating_skillmod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Guidance" for 1d4 active and "Being Cool" for +2 active, I will get a return string " + 1d4 [Guidance] + 2 [Being Cool]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_AC_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Save Modifiers (repeating_savemod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Shield of Faith" with a value of 2 active, I will get a return string " + 2 [Shield of Faith]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Damage_Modifiers || Pass a character ID and TWO string variable to set the return value. The first string will be for normal damage, and the second will be the additional damage on a crit. This procedure will look through the Global Damage Modifiers (repeating_damagemod_*) for rows that are active (checked on the character sheet) and return two strings with the dice rolls and descriptions for them (for example, if I have "Sneak Attack" with a value of 1d6 normal and 1d6 critical damage active, I will get a return string " + 1d6 [Sneak Attack]" and another string of " + 1d6 [Sneak Attack CRIT]" that can be used in a dice rolls.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_DivineSmiteDice || Used to calculate the number of dice to be rolled for a paladin's Divine Smite. Pass a target token id, a spell slot level, and a string variable to be set to the dice roll amount based on the NPC_TYPE attribute of the target token. The returned variable will contain a dice roll (like "3d8" that can be used in a --= line)<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Character_Summary || Outputs a mini character sheet, including clickable buttons for attacks, actions, legendary actions, etc. Will automatically detect a PC vs NPC and output the appropriate sections.<br />
|}<br />
<br />
Due to formatting issues with the Wiki, the library code has been moved to a [https://gist.github.com/kjaegers/52f6049ddd257f0a1288aca4bbde13c5 GITHUB GIT]. Please view the GIST in raw mode and copy the text and paste it into a handout called "ScriptCards Library dnd5elib" in your Roll20 Game.<br />
<br />
== What to Know if you are Coming from PowerCards ==<br />
<br />
''Note: This section is a work in progress.''<br />
<br />
While ScriptCards and PowerCard have very similar output goals, their internals and use are quite different. The table below summarizes some of the major differences between the scripts.<br />
<br />
::{| class="wikitable"<br />
|-<br />
! PowerCards !! ScriptCards <br />
|-<br />
| With a handful of exceptions, all lines in a PowerCard macro are intended to produce a line of output on the final card. || With ScriptCards, ONLY the <code>--+</code> and <code>--*</code> statement types produces output <br />
|-<br />
| PowerCards lines begin with two dashes (<code>--</code>) followed by a unique tag name for the line, followed by a vertical bar and the content for the line. || ScriptCards lines begin with two dashes (<code>--</code>) followed by a '''statement type identifier''', which is a single character that identifies the type of line to the interpreter. This is followed by a tag (frequently optional), a vertical bar, and the parameters for the statement being executed.<br />
|-<br />
| PowerCard macros are always processed top to bottom. Lines can be hidden so they don't output anything, but there is no looping or branching (--SkipTo looks like a branch, but it just hides all of the lines until the referenced label. || ScriptCards scripts support true branching, including direct branching (<code>--^</code>) and procedure branching (<code>--></code>) and (<code>--<</code>). Procedures support parameters and a call stack so procedures can be nested to call other procedures.<br />
|-<br />
| All lines in a PowerCards macro need to have unique tags because PowerCards builds the card as a single JavaScript object using the tag names to store what will be displayed. This is why repeated tag names always result in the last one being shown. || ScriptCards tags do not need to be unique, and in the case of many line types are optional.<br />
|-<br />
| PowerCards conditionals result in either showing or hiding the line they are on. || ScriptCards conditionals '''''only''''' support branching as the result of the comparison. This branching can be direct (a GOTO) or procedural (a GOSUB) '''''NOTE: As of version 1.2.0, ScriptCards also supports roll/string variable assignment as a result of conditional evaluation'''''<br />
|-<br />
| PowerCards relies on the Roll20 [[Quantum Roll]] server and inline rolls for all dice functions || ScriptCards includes its own dice roll parser, and '''''does not support''''' inline rolls.<br />
|-<br />
| PowerCards RollIDs (often mistaken for variables) are assigned by analyzing the results of an inline roll, and cannot be referenced in other rolls, so you can't roll a <code>1d4</code> and then roll a <code>1d20</code> and add the <code>1d4</code> result because all of the rolls happen on the chat server before PowerCards gets the macro text. || ScriptCards supports two types of variables: Roll Variables and String Variables. Because ScriptCards uses its own roll parser and is not dependent upon the chat server, rolls and their results can be used in other rolls, math functions, output, etc.<br />
|}<br />
<br />
== Example Scripts ==<br />
<br />
Below are some sample scripts that utilize the various statement types in ScriptCards:<br />
<br />
=== Divine Smite ===<br />
<br />
This script will prompt the user for a spell slot level to expend on a divine smite. It will check the target's npc_type to see if it is an Undead or Fiend, which adds an additional d8 to the smite roll.<br />
<br />
[[File:ScriptCards Divine Smite.png|Divine Smite Script Output]]<br />
<br />
<pre><br />
!scriptcard {{<br />
--#title|Divine Smite<br />
--=DiceCount|?{Spell Slot Level?|1|2|3|4|5|6|7|8|9} + 1<br />
--=IsFiendOrUndead|0<br />
--?"@{target|npc_type}" -inc fiend|>IsBoosted<br />
--?"@{target|npc_type}" -inc undead|>IsBoosted<br />
--=TotalDice|[$DiceCount] + [$IsFiendOrUndead]<br />
--=SmiteRoll|[$TotalDice]d8<br />
--#emoteText|@{selected|token_name} smites @{target|token_name}<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
--+Smite|deals [$SmiteRoll] radiant damage.<br />
--X|<br />
<br />
--:IsBoosted|<br />
--=IsFiendOrUndead|1<br />
--<|<br />
}}<br />
</pre><br />
<br />
==== How It Works ====<br />
<br />
The first line sets the "title" card parameter to "Divine Smite".<br />
<br />
Line 2 Shows a query to the user asking for the spell slot level, adds one and stores the value in the "DiceCount" Roll Variable. The query/dropdown is generated by the chat server prior to the script being executed.<br />
<br />
Line 3 defaults the "IsFiendOrUndead" Roll Variable to 0.<br />
<br />
Lines 4 and 5 compare the target's "npc_type" attribute (passed by the chat server as text) to see if they include either "undead" or "fiend". If true, the IsBoosted subroutine will be called. No parameters are passed to this subroutine.<br />
<br />
Line 6 sets the "TotalDice" variable to the base (DiceCount) number plus the IsFiendOrUndead number, which will be a 0 or a 1.<br />
<br />
Line 7 calculates "SmiteRoll" by rolling a number of d8 equal to the "TotalDice" value.<br />
<br />
Lines 8-10 set the parameters for the emote, which appears above the card content. By setting the sourceToken and the targetToken, their icons will appear in the emote surrounding the text describing the action.<br />
<br />
Line 11 is the only line that actually produces output on the card. It results in "Smite deals # radiant damage".<br />
<br />
Line 12 ends the script execution, preventing the script from continuing and running the subroutines out of context.<br />
<br />
Lines 14-16 are the IsBoosted subroutine, starting with the :IsBoosted label. The IsFiendOrUndead variable is set to 1, and a return from subroutine is executed.<br />
<br />
=== Magic Missile ===<br />
<br />
This script demonstrates using a loop and calling a subroutine to fire a number of missiles determine by the spell slot level used to cast the spell.<br />
<br />
[[File:ScriptCards_MagicMissile_Fixed.png|Magic Missile Script Output]]<br />
<br />
<pre><br />
!scriptcard {{ <br />
--#title|Magic Missile<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
--=MissileCount|?{Spell Slot Level?|1|2|3|4|5|6|7|8|9} + 2<br />
--=DisplayCount|1<br />
--=MissileDamage|0<br />
--#leftsub|Slot level ?{Spell Slot Level?}<br />
--#rightsub|Ranged Attack<br />
--#emoteText|Fred uses a level ?{Spell Slot Level?} spell slot to fire [$MissileCount.Total] missiles of magical force!<br />
--:MissileLoop|<br />
-->FireMissile|<br />
--=DisplayCount|[$DisplayCount] + 1<br />
--?[$DisplayCount] -le [$MissileCount]|MissileLoop<br />
--+Total|Total damage is [$MissileDamage]<br />
--X|<br />
<br />
--:FireMissile|<br />
--=ThisMissile|1d4 + 1<br />
--=MissileDamage|[$MissileDamage] + [$ThisMissile]<br />
--+Missile|[$DisplayCount.Total] Hits for [$ThisMissile] [b]force[/b] damage<br />
--<|<br />
}}<br />
</pre><br />
<br />
==== How It Works ====<br />
<br />
Lines 1-3 set the card title, the source token and the target token. Setting these tokens causes their icons/avatars to appear in the Emote section of the card.<br />
<br />
Line 4 asks the user what spell slot level they wish to use to cast magic missile. The number of missiles fired is equal to 2 plus the spell level, and this is stored in the MissileCount variable.<br />
<br />
Line 5 stores a 1 in the DisplayCount variable. This will be used to control the loop to determine the number of missiles fired and the missile number when displaying damage rolls.<br />
<br />
Line 6 initializes MissileDamage to 0<br />
<br />
Line 7 sets the left subtitle to the text "Slot Level #", where # is the spell slot level being used.<br />
<br />
Line 8 sets the right subtitle to the text "Ranged Attack".<br />
<br />
Line 9 sets the emoteText parameter with a description of the action, including the slot level and number of missiles fired.<br />
<br />
Line 10 is a label for the missile firing loop<br />
<br />
Line 11 Calls the "FireMissile" subroutine<br />
<br />
Line 12 increases the DisplayCount variable by 1<br />
<br />
Line 13 Checks to see if there are still missles to fire (DisplayCount <= MissileCount) and if so branches to MissileLoop<br />
<br />
Line 14 Displays the total damage dealt by the spell.<br />
<br />
Line 15 stops execution of the script to prevent out of context execution of the subroutine.<br />
<br />
Lines 76-21 are the FireMissile subroutine, beginning with the FireMissile label. The 1d4+1 is rolled and assigned to "ThisMissile". The result is added to the existing MissileDamage total, and a line for the current missile is displayed with the missile number and the damage for the missile.<br />
<br />
=== Longsword Attack ===<br />
<br />
This script demonstrates a standard 5E D&D melee weapon attack, including detection of misses, fumbles, hits, and critical hits. If installed, alterbars is used to decrement the target's BAR3 value by the damage dealt.<br />
<br />
[[File:ScriptCards Longsword.png|Longsword Script Output]]<br />
<br />
<pre><br />
!scriptcard {{<br />
--#title|Longsword<br />
--#leftsub|Melee Attack<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
--#emoteText|@{selected|token_name} attacks @{target|token_name}<br />
--=TargetAC|@{target|npc_ac}<br />
--?[$TargetAC.Total] -gt 0|DoneWithAC<br />
--=TargetAC|@{target|ac}<br />
--:DoneWithAC|<br />
--=AttackRoll|1d20 + @{selected|strength_mod} [STR] + @{selected|pb} [PROF]<br />
--+Attack|@{selected|token_name} rolls [$AttackRoll] vs AC [$TargetAC].<br />
--?[$AttackRoll.Base] -eq 20|Crit<br />
--?[$AttackRoll.Base] -eq 1|Fumble<br />
--?[$AttackRoll.Total] -ge [$TargetAC.Total]|Hit<br />
--+Miss|The attack missed.<br />
--^Final|<br />
<br />
--:Fumble|<br />
--+Fumble!|The attack went horribly wrong.<br />
--^Final|<br />
<br />
--:Hit|<br />
--=Damage|1d8 + @{selected|strength_mod} [STR]<br />
--+Hit!|The attack hit @{target|token_name} for [$Damage] slashing damage.<br />
--@alter|_target|@{target|token_id} _bar|3 _amount|-[$Damage]<br />
--^Final|<br />
<br />
--:Crit|<br />
--=Damage|1d8 + @{selected|strength_mod} [STR] + 1d8 [CRIT]<br />
--+Critical Hit!|The attack hit @{target|token_name} for [$Damage] slashing damage.<br />
--@alter|_target|@{target|token_id} _bar|3 _amount|-[$Damage]<br />
<br />
--:Final|<br />
}}<br />
</pre><br />
<br />
==== How it Works ====<br />
<br />
In lines 1-5, we set the title, subtitle, and emote text along with the tokens for the emote area.<br />
<br />
Lines 6-9 allow us to determine the AC of the target. On the 5E Roll20 sheet, NPCs armor class is stored in "npc_ac", while PCs armor class is in "ac". First we grab npc_ac and if it is zero, we check AC.<br />
<br />
Line 10 rolls the attack roll, rolling 1d20 and adding the attacker's strength modifier and proficiency bonus<br />
<br />
Line 11 displays the result of the attack roll on the card<br />
<br />
Lines 12-14 determine what kind of result the attack had. If the .Base value of the roll was 20, we branch to "Crit". If it was 1, we branch to "Fumble". If the .Total value of the roll was greater than or equal to the AC that was determined in Lines 6-9, we branch to Hit.<br />
<br />
Assuming we didn't branc anywhere, the result of the attack was a miss, so we display that on line 15 and then branch to "Final"<br />
<br />
This is followed by three branch segments, :Fumble, :Hit, and :Crit. A fumble displays a text message and branches to :Final.<br />
<br />
On a hit or a crit, we roll Damage (adding additional damage dice on a crit). We display a "Hit!" or "Critical Hit!" message and then make an API call to AlterBars, passing it the token id, bar we want to modify (3 in this case), and the amount we want to modify by the Damage value.<br />
<br />
=== Party Health Status ===<br />
<br />
This example calculates the current Hit Points remaining and HP percentage for each character and creates a color-coded display with the current party status.<br />
<br />
[[File:ScriptCards Party Health.png]]<br />
<br />
<pre><br />
!scriptcard {{<br />
--#title|Party Status<br />
--#titleCardBackground|#33CC33<br />
--#oddrowbackground|#bfee90<br />
--#evenrowbackground|#90eebf<br />
-->HealthCheck|@{Quej Grastra|character_id}<br />
-->HealthCheck|@{Brim Cheuto|character_id}<br />
-->HealthCheck|@{Odug Ututees|character_id}<br />
--X|End of card Execution<br />
<br />
--:HealthCheck|<br />
--=HealthPerc|[*[%1%]:hp] / [*[%1%]:hp^] * 100 \ 1<br />
--=HealthColor|000000<br />
--?[$HealthPerc.Total] -gt 50|HealthSkip<br />
--=HealthColor|FF0000<br />
--:HealthSkip|<br />
--+[*[%1%]:character_name]|has [#[$HealthColor.RollText]][*[%1%]:hp] of [*[%1%]:hp^][/#] HP [R]([$HealthPerc.Total]%)[/R]<br />
--<|End of HealthCheck<br />
}}<br />
</pre><br />
<br />
==== How it Works ====<br />
<br />
Lines 1-4, we set the card title, and set the title background and row background colors to shades of green.<br />
<br />
Lines 5-7 make gosub calls the the "HealthCheck" subroutine, passing in the character ID of each of the named characters (these are the names of the characters in my test game)<br />
<br />
Line 8 terminates the script execution.<br />
<br />
The remaining lines of the script are the HealthCheck subroutine, which works like this:<br />
<br />
Line 10 is the subroutine label (:HealthCheck)<br />
<br />
Line 11 uses the character id passed as a parameter and combines it with character attribute lookup *(...) to retrieve the value of "hp" and "hp<nowiki>^</nowiki>" for the character. The <nowiki>^</nowiki> character is used to specify that we want the MAX value for this attribute for the second call. We divide these two numbers and multiple by 100 to get a percentage. Finally, we use integer division by 1 to round the percentage and drop the decimals. The end result gets stored in the HealthPerc roll variable.<br />
<br />
Line 12 defaults to color of the health text to black<br />
<br />
Line 13 check to see if the health percentage is greater than 50. If so, it branches to HealthSkip, preventing the script from executing line 13.<br />
<br />
Line 14 sets the color of the health text to red<br />
<br />
Line 15 is the label that will be branched to from Line 13 to skip the red coloring<br />
<br />
Line 16 again uses character attribute substitution and the passed parameter value to output a display line containing the character name, the colorized health total, and the percentage value. The percentage is right-justified.<br />
<br />
Line 17 returns from the HealthCheck subroutine.<br />
<br />
=== Expanded Magic Missile Script ===<br />
<br />
This is the expanded and enhanced version of the Magic Missile script covered in {{yt|watch?v=u50xvNzS9Zk | this video}}. It includes visual and audio effects, checking and deducting spell slots, and applying damage using either Token-Mod or Alterbars.<br />
<br />
<pre><br />
!scriptcard {{ <br />
--#title|Magic Missile<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
<br />
-->GetAndCheckSlotInformation|<br />
<br />
--=MissileCount|[$SlotLevel] + 2<br />
--=DisplayCount|1<br />
--=MissileDamage|0<br />
--#leftsub|Slot level [$SlotLevel]<br />
--#rightsub|Ranged Attack<br />
--#emoteText|@{selected|character_name} uses a level [$SlotLevel.Total] spell slot to fire [$MissileCount.Total] missiles of magical force!<br />
<br />
--:MissileLoop|<br />
-->FireMissile|<br />
--=DisplayCount|[$DisplayCount] + 1<br />
--?[$DisplayCount] -le [$MissileCount]|MissileLoop<br />
--+Total|Total damage is [$MissileDamage]<br />
-->DeductSpellSlot|<br />
--#rightsub|Level [$SlotLevel] Left: [$SlotsRemaining] <br />
-->PlayEffects|none;burst-smoke;beam-magic;spell_01<br />
-->ApplyDamageTokenmod|@{target|token_id};3;-[$MissileDamage]<br />
-->ApplyDamageAlterbars|@{target|token_id};3;-[$MissileDamage]<br />
--X|<br />
<br />
--:FireMissile|<br />
--=ThisMissile|1d4 + 1<br />
--=MissileDamage|[$MissileDamage] + [$ThisMissile]<br />
--+Missile|[$DisplayCount.Total] Hits for [$ThisMissile] [b]force[/b] damage<br />
--<|<br />
<br />
--:GetAndCheckSlotInformation|<br />
--=SlotLevel|?{Spell Slot Level?|1|2|3|4|5|6|7|8|9}<br />
--=SlotsTotal|[*S:lvl[$SlotLevel]_slots_total]<br />
--=SlotsExpended|[*S:lvl[$SlotLevel]_slots_expended]<br />
--?[$SlotsExpended.Total] -ge [$SlotsTotal.Total]|NoSlotsLeft<br />
--<|<br />
<br />
--:NoSlotsLeft|<br />
--+|[*S:character_name] has no level [$SlotLevel.Total] spell slots available.<br />
--X|<br />
<br />
--:DeductSpellSlot|<br />
--=SlotsExpended|[$SlotsExpended] + 1<br />
--@setattr|_charid [*S:character_id] _lvl[$SlotLevel]_slots_expended|[$SlotsExpended] _silent<br />
--=SlotsRemaining|[$SlotsTotal] - [$SlotsExpended]<br />
--<|<br />
<br />
--:PlayEffects|Parameters are : source effect; target effect; line effect; sound effect<br />
--vtoken|@{selected|token_id} [%1%]<br />
--vtoken|@{target|token_id} [%2%]<br />
--vbetweentokens|@{selected|token_id} @{target|token_id} [%3%]<br />
--@roll20AM|_audio,play,nomenu|[%4%]<br />
--<|<br />
<br />
--:ApplyDamageTokenmod|Parameters are tokenid;bar#;amount<br />
--@token-mod|_ignore-selected _ids [%1%] _set bar[%2%]_value|[%3%]<br />
--<|<br />
<br />
--:ApplyDamageAlterbars|<br />
--@alter|_target|[%1%] _bar|[%2%] _amount|[%3%]<br />
--<|<br />
}}<br />
</pre><br />
<br />
[[Category:Featured articles]]</div>5004103https://wiki.roll20.net/Script:ScriptCardsScript:ScriptCards2021-09-28T08:04:18Z<p>5004103: /* Character/Token Attributes */</p>
<hr />
<div>{{revdate}}<br />
== Introduction ==<br />
'''ScriptCards''' provides a script interpreter that can be used to create powerful macros that display the results of player/NPC actions, or display other information in a pleasing visual format in your game's chat window. The scripting language contains variables (both dice-roll (enhanced numerics) and strings) as well, conditionals, branching, subroutines with parameters, and a set of built-in functions to simplify working with Roll20 information.<br />
{{script overview<br />
|name=ScriptCards<br />
|author={{user profile|2365448|Kurt J.}}<br />
|code=<br />
|version=1.4.0e<br />
|lastmodified=2021-09-24}}<br />
ScriptCards is not game-system specific, and can be used with any system/sheet. Near the end of this Wiki there is a section set aside for libraries that can implement system-specific tasks, with the hope that enthusiasts playing particular systems will create and share utility functions that can be utilized by the wider community.<br />
<br />
The default display style for ScriptCards output is similar to the format used to document player and NPC abilities in Dungeons and Dragons 4th Edition, but does not have any system ties to D&D4E.<br />
<br />
Current OneClick Version : 1.4.0e<br />
<br />
Current Development Version : 1.4.4<br />
<br />
'''''<big>Critically Important: ScriptCards does not use/parse inline rolls. ScriptCards includes its own built-in dice roll parser to allow for the use of variables inside dice rolls. As of version 1.2.3, ScriptCards will now take inline rolls and substitute the total result value in statement strings, meaning that you can utilize inline rolls but ScriptCards will only see the result of the roll, and not parse the roll components itself.</big>'''''<br />
<br />
* {{fpl|9752053/ ScriptCards thread}}<br />
** {{fpl|10000297/ Scritpcard API Working and Sharing}}<br />
* https://github.com/kjaegers/ScriptCards/tree/main/ScriptCards_API - GitHub repository for source before the one-click version is updated.<br />
* {{yt.be|hyR7Jnq4mQM ScriptCards Intro}} 45min, Jan 2021<br />
* {{yt.be|u50xvNzS9Zk ScriptCards Magic Missile Deep Dive}} 39min, Feb 2021<br />
<br />
<br />
__TOC__<br />
=== Is ScriptCards Related to [[PowerCards]]? ===<br />
<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
Check the '''[[#What to Know if you are Coming from PowerCards|What to Know if you are Coming from PowerCards]]'''-section for a comparison table between the two scripts.<br />
<br />
== What is a ScriptCard Script ==<br />
<br />
A ScriptCard Script is text written into the chat window (either typed directly, pasted, or run via a macro) that will produce a card of information in the [[text Chat|chat window]]. A ScriptCard Script is composed of an [[API]] command: <code><nowiki>!scriptcard {{ }}</nowiki></code> enclosing any number of lines that determine the output that will be added to the card. At it simplest, the following macro:<br />
<br />
<pre>!scriptcard {{ }}</pre><br />
<br />
Will produce just a title card that displays “ScriptCards” as the name:<br />
<br />
[[File:Scriptcard blank.png]]<br />
<br />
Of course, this is just the simplest type of macro and isn’t very useful. In order to produce useful output, we need to include lines between the <code><nowiki>{{</nowiki></code> and <code><nowiki>}}</nowiki></code> that direct the API script as to what it should do.<br />
<br />
== Structure of a ScriptCard Line ==<br />
<br />
All ScriptCard lines begin with two dashes, followed by an ''statement identifier character'' that lets ScriptCards what type of line it is. There are several of these, and they are detailed in the next section. After the line type identifier, a Tag name 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.<br />
<br />
Following the Tag is a vertical bar, and then the content of the line itself. Again, each type of line might interpret this content differently.<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Identifier !! Statement Type !! Tag !! Content !! Notes<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--/</nowiki> || Comment || unused || unused || The <code>--/</code> 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--#</nowiki> || 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").<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--+</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--=</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--&</nowiki> || Assign String 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. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--@</nowiki> || 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 (i.e., [[TokenMod|!token-mod]], or [[ChatSetAttr|!setattr]], etc.)<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--:</nowiki> || 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<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--^</nowiki> || Branch To || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--></nowiki> || Call Procedure || 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<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--<</nowiki> || 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.<br />
|- <br />
| style="white-space:nowrap" | <nowiki>--?</nowiki> || Conditional Branch || Condition to be evaluated || True Branch Label<nowiki>|</nowiki>False Branch Label || The condition will be evaluated and execution will jump to one of the two indicated branches (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 included a semicolon separated list of parameters. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--s</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--l</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--v</nowiki> || 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+'''''<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--e</nowiki> || Echo to Chat || Name to send chat command as || Chat message to send || Variable substitution takes place on the tag and content.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--R</nowiki> || Retrieve Repeating Section Row information || "find", "first", or "next" || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--~</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--c</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--i</nowiki> || Information Request || User Prompt;Button Caption || InfoType;VariableName;ParameterText || See full documentation below.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--d</nowiki> || 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. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--%</nowiki> || 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. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--*</nowiki> || 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.<br />
|}<br />
<br />
== ScriptCard Statement Type Details ==<br />
The sections below detail the individual statement types supported by ScriptCards<br />
<br />
=== Comment (--/) ===<br />
<br />
A --/ statement is ignored by the ScriptCards parser. You can use this type of statement to add comments and informational text to your script. <br />
<br />
Example:<br />
<pre><br />
!script {{<br />
--/|Script Name : Fireball<br />
--/|Purpose : Allow the player to cast a fireball and blow stuff up!<br />
.<br />
.<br />
.<br />
}}<br />
</pre><br />
<br />
=== Set Parameter (--#) ===<br />
<br />
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.<br />
<br />
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.<br />
<br />
'''''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.'''''<br />
<br />
Examples:<br />
<pre><br />
--#title|Magic Missile<br />
--#leftsub|Level 1 Spell<br />
--#rightsub|Force Damage<br />
</pre><br />
<br />
The three examples above set the “title”, “leftsub”, and “rightsub” values for the card to the content value for the line. <br />
<br />
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.<br />
Settings Lines do not produce output lines on the card.<br />
<br />
The following settings are available (note that parameter names are ''not'' case sensitive):<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Name !! Effect/Use !! Default Value !! Type<br />
|-<br />
| 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<br />
|-<br />
| allowplaintextinrolls || If set to a non-zero value, plain character text in rolls will be copied to the roll text || 0 || Per-Line<br />
|-<br />
| bodyFontFace || Name of the font used in the card rows || Helvetica || Global<br />
|-<br />
| bodyFontSize || Size of the text in the card rows || 14px || Global<br />
|-<br />
| bodybackgroundimage || Specify an image (content for a CSS background-image tag) for the body area || none || Global<br />
|-<br />
| buttonBackground || Background color for buttons created with [button][/button] || #1C6EA4 || Per-Line<br />
|-<br />
| buttonBorderColor || Border (outline) color for buttons created with [button][/button] || #999999 || Per-Line<br />
|-<br />
| buttonFontFace || Font Family specifier for captions on buttons created with [button][/button] || Tahoma || Per-Line<br />
|-<br />
| buttonFontSize|| Text size for captions on buttons created with [button][/button] || x-small || Per-Line<br />
|-<br />
| buttonTextColor|| Text color of labels on buttons created with [button][/button] || #FFFFFF || Per-Line<br />
|-<br />
| 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<br />
|-<br />
| deferralcharacter || Changes the meta script deferral sequence to the specified value || ^ || Per-Line<br />
|-<br />
| diceFontColor|| Color of the dice created with the [d4] [d6], etc. formatting markers || #1C6EA4 || Per-Line<br />
|-<br />
| dicefontsize || Size of the dice created with the [d4] [d6], etc. formatting markers || 3.0em || Per-Line<br />
|-<br />
| 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<br />
|-<br />
| disablerollprocessing || If set to a non-zero value, --= lines will not process dice rolls strings || 0 || Per-Line<br />
|-<br />
| emoteBackground || Background color of the emote area || #f5f5ba || Global<br />
|-<br />
| emoteFont || Name of the font used in emote area (above the title of the output card) || Georgia || Global<br />
|-<br />
| emoteFontColor || Color of the font in the emote area || None (Empty) || Global<br />
|-<br />
| emoteFontSize || Size of the font used in the emote area || 14px || Global<br />
|-<br />
| emoteFontWeight || Font weight for the font in the emote area || bold|| Global<br />
|-<br />
| emoteState || If set to anything other than "visible", the emote portion of the card will not be displayed || visible || Global<br />
|-<br />
| emoteText || Text to display in the emote portion of the card || None (Empty) || Global<br />
|-<br />
| emotefont || Name of the font used in the emote text area || font-family: Georgia, serif; font-weight: bold; || Global<br />
|-<br />
| evenRowBackground || Hex code for the background color for even rows || #eeeeee || Per-Line<br />
|-<br />
| evenRowFontColor || Hex code for the text color for even rows || #000000 || Per-Line<br />
|-<br />
| evenrowbackgroundimage || Specify an image (content for a CSS background-image tag) for the even card rows || none || Per-Line<br />
|-<br />
| executionlimit || Maximum number of script lines the interpreter will try to execute. This prevents "infinite loop" sandbox crashes || 40000 || Global<br />
|-<br />
| hideCard || If set to any non-default value, the entire card output will be suppressed || 0 || Global<br />
|-<br />
| 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<br />
|-<br />
| 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<br />
|-<br />
| lineheight || Vertical size of each line on the output card || normal || Per-Line<br />
|-<br />
| nominmaxhighlight || If set to anything other than "0", rolls will not display crit/fumble/mixed highlight colors. || 0 || Per-Line<br />
|-<br />
| norollhighlight || If set to anything other than "0", rolls will not be formatted (plain numbers) but will still get a tooltip with details ('''''v1.3.6b+''''') || 0 || Per-Line<br />
|-<br />
| oddRowBackground || Hex code for the background color for even rows || #d0e4f5 || Per-Line <br />
|-<br />
| oddRowFontColor || Hex code for the text color for odd rows || #000000 || Per-Line<br />
|-<br />
| oddrowbackgroundimage || Specify an image (content for a CSS background-image tag) for the odd crd rows || none || Per-Line<br />
|-<br />
| reentrant || Used to name a script for rentrant button use || 0 || Global<br />
|-<br />
| 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)0 || Global<br />
|-<br />
| rollhilightlineheight || Determines the height of the hilight box placed around roll results ('''''1.4.2+''''') || 1.0em || Per-Line<br />
|-<br />
| roundUp || If set to a non-default value, integer division will round up instead of down || 0 || Per-Line<br />
|-<br />
| showfromfornonwhispers || If set to a non-zero value, will include the sender on cards that aren't whispered || 0 || Global<br />
|-<br />
| 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<br />
|-<br />
| subtitleFontColor || Color of the text in the subtitle areas || #FFFFFF || Global<br />
|-<br />
| subtitleFontFace || Name of the font used on the subtitle sections || Tahoma || Global<br />
|-<br />
| subtitleFontSize || Size of the subtitle font || 13px || Global<br />
|-<br />
| subtitleSeperator || The character(s) that will be placed between leftsub and rightsub || <nowiki>&#x2666</nowiki>; || Global<br />
|-<br />
| tableBorderRadius || CSS specifier for how rounded the borders of the output card are. Use "0px;" for square borders || 6px; || Global<br />
|-<br />
| tableShadow || CSS specifier for the drop shadow under the output card || 5px 3px 3px 0px #aaa; || Global<br />
|-<br />
| tablebgcolor || Background color of the whole card. '''''Normally not visible''''' || #EEEEEE || Global<br />
|-<br />
| tableborder || Color of the border that surrounds the whole card || 2px solid #000000; || Global<br />
|-<br />
| 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<br />
|-<br />
| timezone || IANA Specifier for the local time zone, used in system/date functions || merica/New_York || Per-Line<br />
|-<br />
| title || Text displayed in the title area of the card || ScriptCards || Global<br />
|-<br />
| titleCardBackground || A hex color code representing the background color of the title area. || #1c6ea4 || Global<br />
|-<br />
| titleFontColor || Color of the text on the card title || #FFFFFF || Global<br />
|-<br />
| titleFontFace || Name of the font used on the title area || Contrail One || Global<br />
|-<br />
| titleFontLineHeight || Line spacing on the title area || 1.2em || Global<br />
|-<br />
| titleFontSize || Size of the title font || 1.2em || Global<br />
|-<br />
| titlecardbackgroundimage || Specify an image (content for a CSS background-image tag) for the title card area || none || Global<br />
|-<br />
| titlecardbottomborder || Border CSS specifier for the bottom of the title card area || 2px solid #444444; || Global<br />
|-<br />
| titlecardgradient || If set to non-zero value, will place a vertical gradient on the title card area || 0 || Global<br />
|-<br />
| usehollowdice || If set to a non-zero value, the hollow/outline versions of the dice fonts will be used || 0 || Per-Line<br />
|-<br />
| whisper|| Comma separated list of who to whisper the output to. Use "gm" for [[GM|GMs]] and "self" for the sender || none || Global|}<br />
|}<br />
<br />
''Setting Lines do not produce output lines on the card''<br />
<br />
=== Direct Output (--+) ===<br />
<br />
A direct output line display 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.<br />
<br />
Examples of Direct Output lines:<br />
<pre><br />
--+Hello|World<br />
--+Attack|The monster rolls [$Attack] to hit!<br />
--+Damage|@{target|token_name} is hit for [$Damage] [#3333AA][b]frost[/b][/#] damage.<br />
</pre><br />
<br />
Direct Output lines support inline formatting, roll variable replacement, character attribute references, and procedure variables.<br />
<br />
=== GM Output (--*) ===<br />
<br />
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. <br />
<br />
Example:<br />
<pre><br />
--+PlayerLine|This line is shown on the public card<br />
--*GMLine|This line will only be shown to GMs, on a separate card.<br />
</pre><br />
<br />
=== Roll Variable Assignment (--=) ===<br />
<br />
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.<br />
<br />
'''''All components of a roll equation should be separated with spaces.'''''<br />
<br />
Examples:<br />
<pre><br />
--=MissileDamage|1d4 + 1<br />
--=Attack|1d20 + @{selected|strength_mod} [STR] + @{selected|pb} [PROF]<br />
</pre><br />
<br />
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. Text enclosed in square brackets ([]) is considered "flavor text" and will be added to the result text but does not impact the roll result.<br />
<br />
The following dice formats are supported:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Format Pattern !! Example !! Description<br />
|-<br />
| XdY || 3d8 || Simple format. Roll a Y-sided die X times<br />
|-<br />
| XdYkhZ || 2d20kh1 || Roll Y-sided die X times and keep the highest Z number of dice<br />
|-<br />
| XdYklZ || 4d6kl3 || Roll Y-sided die X times and keep the lowest Z number of dice <br />
|-<br />
| XdY>Z || 5d6>3 || Roll Y-sided die X times and count a 1 for each roll greater than Z <br />
|-<br />
| XdY<Z || 5d6<3 || Roll Y-sided die X times and count a 1 for each roll less than Z <br />
|}<br />
<br />
'''''Note: The dice formulae below are supported in the development version of ScriptCards and will be merged with the table above when activated on OneClick'''''<br />
::{| class="wikitable"<br />
|-<br />
! Format Pattern !! Example !! Description<br />
|-<br />
| 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<br />
|-<br />
| 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<br />
|-<br />
| 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)<br />
|-<br />
| 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<br />
|}<br />
<br />
The following operators are supported in a roll equation:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Operator !! Operation<br />
|-<br />
| + || Addition <br />
|-<br />
| - || Subtraction <br />
|-<br />
| * || Multiplication <br />
|-<br />
| / || Division <br />
|-<br />
| \ || Integer Division (Rounds down) <br />
|-<br />
| % || Modulo (Remainder of Divison)<br />
|}<br />
<br />
Roll Variables can be accessed at any time after they have been created by using the [$VariableName] format, with the following optional modifiers:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Modifier !! Meaning<br />
|-<br />
| No modifier || In a Direct Output Line (<nowiki>--+</nowiki>) 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<br />
|-<br />
| .Total || The end result of the roll equation as an unformatted number <br />
|-<br />
| .Base || The cumulative result of any dice rolled in the Roll Text (Numeric modifiers are not included) <br />
|-<br />
| .Ones || The number of dice in the roll that came up as 1s <br />
|-<br />
| .Aces || The number of dice in the roll that came up as the maximum number on the die <br />
|-<br />
| .Odds || The number of dice in the roll that came up with an odd number <br />
|-<br />
| .Evens || The number of dice in the roll that came up with an even number <br />
|-<br />
| .RollText || The raw text of the roll that was use to generate the results <br />
|-<br />
| .Text || A text representation of the results of the roll, including the numbers rolled for each die <br />
|-<br />
| .tableEntryText || The text portion of the result of a table roll<br />
|-<br />
| .tableEntryImgURL || The image source portion of the result of a table roll<br />
|-<br />
| .tableEntryValue || Numeric value of tableEntryText (via parseInt). If a non-numeric value, will be 0<br />
|-<br />
| .Raw || The total numeric result without any formatting, even if placed somewhere formatting would normally be done. <br />
|}<br />
<br />
Examples:<br />
<pre><br />
--+Total Damage|[$MissileDamage.Total] (roll was 1d4+1)<br />
--+Base Damage|[$MissileDamage.Base] (without the +1)<br />
--=Attack|1d20 + @{selected|strength_mod} [STR] + @{selected|pb} [PROF] + [$BlessBonus] [Bless]<br />
</pre><br />
<br />
In this case, 1d4 will be rolled and stored in “BlessBonus”, which can then be used in the Attack line.<br />
<br />
'''''Mathematical Functions in Roll Expressions '''''<br />
<br />
The ScriptCards roll parser works from left to right, always maintaining a current value and applying whatever comes next to the total. The following in-line functions to the roll parser. These are:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Expression !! Meaning<br />
|-<br />
| {ABS} || Absolute Value<br />
|-<br />
| {CEIL} || Ceiling value (round up to the next whole number)<br />
|-<br />
| {FLOOR} || Floor value (round down to the next whole number)<br />
|-<br />
| {ROUND} || Round value (round up if the decimal portion is greater than 0.5, otherwise round down)<br />
|-<br />
| {NEGATE} || Multiply the value by negative one.<br />
|-<br />
| {SQRT} || Take the square root of the running value. ('''''1.4.1+''''')<br />
|-<br />
| {SQUARE} || Square the running value. ('''''1.4.2+''''')<br />
|-<br />
| {CUBEROOT} || Take the cube root of the running value. ('''''1.4.2+''''')<br />
|-<br />
| {CUBE} || Cube the running value. ('''''1.4.2+''''')<br />
|-<br />
| {SIN} || Return the SIN of running value. ('''''1.4.2+''''')<br />
|-<br />
| {COS} || Return the COS of running value. ('''''1.4.2+''''')<br />
|-<br />
| {TAN} || Return the TAN of running value. ('''''1.4.2+''''')<br />
|-<br />
| {ASIN} || Return the ASIN of running value. ('''''1.4.2+''''')<br />
|-<br />
| {ACOS} || Return the ACOS of running value. ('''''1.4.2+''''')<br />
|-<br />
| {ATAN} || Return the ATAN of running value. ('''''1.4.2+''''')<br />
|}<br />
<br />
<br />
'''''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 <nowiki>[[ ]]</nowiki> 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.<br />
<br />
'''''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.<br />
<br />
'''Rolling on Rollable Tables'''<br />
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.<br />
<br />
''Roll Variable Lines do not produce output lines on the card.''<br />
<br />
=== String Variable Assignment (--&) ===<br />
<br />
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:<br />
<br />
<pre><br />
--&MyText|Hello<br />
</pre><br />
<br />
Here, we assign the text "Hello" to the string variable named MyText. You can also append text to a string variable by prefixing the content with a + sign:<br />
<br />
<pre><br />
--&MyText|+ World<br />
</pre><br />
<br />
If run after the statement above, MyText will now contain "Hello World".<br />
<br />
String variables can be referenced using the syntax [&variablename]<br />
<br />
=== Call API (--@) ===<br />
<br />
ScriptCards can use a Call API instruction to execute other API commands. The Tag contains the API 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 API command is executed.<br />
<br />
Examples:<br />
<pre><br />
--@eh|list<br />
--@alter|_target|@{target|token_id} _bar|3 _amount|-[$Damage]<br />
</pre><br />
<br />
In the first example above, the command <code>!eh list</code> will be executed, calling [[EncounterHelper]]. In the second, {{fpl|1216260/ AlterBars}} is called to modify a token's Bar 3 value.<br />
<br />
'''''Note:''''' When ScriptCards (or any API script) runs other API 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).<br />
<br />
See [[API:Script Index]] for more options.<br />
<br />
=== Branch Label (--:) ===<br />
<br />
A branch label defines a line in your code that can be reached by one of the branching instructions (<nowiki>--^</nowiki>, <nowiki>--></nowiki>, or <nowiki>--?</nowiki>). The Tag serves as the label name, and must be unique on the card.<br />
<br />
The vertical bar (|) separator must be present, but the content portion of the line is unused and can be treated as a comment.<br />
<br />
Examples:<br />
<pre><br />
--:MyLoop|<br />
--:CriticalHit|Will jump here if we roll a critical hit!<br />
</pre><br />
<br />
''A Branch Label line does not produce an output line on the card.''<br />
<br />
=== Branch (--^) === <br />
<br />
A Branch line 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.<br />
<br />
Examples:<br />
<pre><br />
--^MyLoop|Jumps to MyLoop<br />
--^SkipCrit|We didn't crit, so skip the Crit code<br />
</pre><br />
<br />
''A Branch line does not produce an output line on the card.''<br />
<br />
=== Call Procedure (-->) ===<br />
<br />
Similar to a branch, a Call Procedure (sometimes knows 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 (<nowiki>--<</nowiki>) 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 (;).<br />
<br />
Examples:<br />
<pre><br />
-->FixFormat|#3333FF;#999999<br />
</pre><br />
<br />
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%].<br />
<br />
=== Return (--<) ===<br />
<br />
A return instruction marks the end of a Gosub procedure. 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.<br />
<br />
Examples:<br />
<pre><br />
--<|<br />
--<|End of MySub<br />
</pre><br />
<br />
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.<br />
<br />
=== Conditional Statement (--?) ===<br />
<br />
A conditional statement contains some equation in the Tag that will be evaluated. '''''If any part of the comparison can/does contain a space, it needs to be surrounded by double quotes'''''<br />
<br />
Based on the true/false result of the evaluation, one of two execution paths will be taken. These execution paths are detailed in the content section of the statement. The "if true" path is specified first (directly after the vertical bar), and the "if false" path is specified after it, also separated by a vertical bar.<br />
<br />
Example:<br />
<pre><br />
--?[$AttackRoll.Total] -ge [$TargetAC]|Hit|Miss<br />
</pre><br />
<br />
'''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.'''<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Branch Format !! Meaning<br />
|-<br />
| Label || If just a label is specified, execution will branch to that label when the comparison is matched.<br />
|-<br />
| >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 <br />
|-<br />
| =VariableName || The roll variable "VariableName" will be assigned the value following a semicolon (ex: --?1 -eq 1|=Roll;1d20)<br />
|-<br />
| &VariableName || The string variable "VariableName" will be assigned the value following a semicolon (ex: --?1 -eq 1|&Result;Hit|&Result;Miss)<br />
|-<br />
| % or %! || The current for...next loop will perform the "next" action (%) or will break out (%!) <br />
|-<br />
| [ || Code block (see below)<br />
|}<br />
<br />
Examples:<br />
<pre><br />
--?[$AttackRoll.Base] -eq 20|CriticalHit<br />
--?[$AttackRoll.Base] -eq 1|>Fumble;@{selected|dexterity_mod}<br />
--?"@{target|npc_type}" -inc "undead"|&MonsterType;Undead|&MonsterType;Not Undead<br />
--?[$Attack.Total] >= [$ArmorClass]|>Hit|>Miss<br />
</pre><br />
<br />
In the first example, if the Base value of AttackRoll is a 20 (natural 20 on the die) execution will branch to the CriticalHit label.<br />
<br />
In the second example, 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%].<br />
<br />
The third example looks for the word "undead" in the npc_type attribute of the targeted character. If it exists in the text, the MonsterType string variable will be set to "Undead", otherwise it will be set to "Not Undead". <br />
<br />
The final example would call 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.<br />
<br />
''Text that does/may contain a space should be enclosed in double quotes.''<br />
<br />
The following comparison operators are available:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Comparator !! Meaning<br />
|-<br />
| -eq || Equal To <br />
|-<br />
| -eqi || Case insensitive Equal To <br />
|-<br />
| -ne || Not Equal To <br />
|-<br />
| -nei || Case insensitive Not Equal To <br />
|-<br />
| -gt || Greater Than <br />
|-<br />
| -ge || Greater Than or Equal To <br />
|-<br />
| -lt || Less Than <br />
|-<br />
| -le || Less Than or Equal To <br />
|-<br />
| -inc || Includes (text strings). <br />
|-<br />
| -ninc || Does Not Include (text strings). <br />
|}<br />
<br />
Multi-part conditionals are supported with -and and -or as separators. For example:<br />
<br />
<pre><br />
--?[$Attack.Total] -ge @{target|npc_ac} -and [$Attack.Base] -ne 20|HitButNotCrit<br />
</pre><br />
<br />
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):<br />
<br />
true AND false OR true<br />
<br />
Will be evaluated as true. The first two (true and false) will be false, but then false OR true will be true.<br />
<br />
Conversely:<br />
<br />
true or false and false<br />
<br />
Will be false, because the first true and false will evaluate to true, and then true and false will be false.<br />
<br />
'''CODE BLOCKS'''<br />
<br />
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.<br />
<br />
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:<br />
<br />
<pre><br />
!script {{<br />
--=Roll|1d2<br />
--+Roll|[$Roll]<br />
--?[$Roll.Total] -eq 2|[<br />
--&Value|Yep!<br />
--+|We are inside the TRUE portion of the block<br />
--]|[<br />
--&Value|Nope<br />
--+|We are inside the FALSE portion of the block<br />
--]|<br />
--+After|the blocks!<br />
--+Value|[&Value]<br />
}}<br />
</pre><br />
<br />
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 --]|. <br />
<br />
At this time, blocks cannot be nested, and can only be created as part of a conditional (--[ is not a valid statement type)<br />
<br />
''A conditional statement does not produce a line of output on the card.''<br />
<br />
=== Case Statement (--c) ===<br />
<br />
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 (:). Each match condition includes a branch label that will be used if the test value matches the item. 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:<br />
<br />
<pre><br />
!script {{<br />
--#title|Case Statement Testing<br />
--=Roll|1d4<br />
--C[$Roll.Total]|1:>One;[$Roll]|2:>Two;[$Roll]|3:>Three;[$Roll]|4:>Four;[$Roll]<br />
--X|<br />
<br />
--:One| --+Value|was One ([%1%]) --<|<br />
--:Two| --+Value|was Two ([%1%]) --<|<br />
--:Three| --+Value|was Three ([%1%]) --<|<br />
--:Four| --+Value|was Four ([%1%]) --<|<br />
}}<br />
</pre><br />
<br />
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 variable as a parameter.<br />
<br />
=== Save and Load (--s and --l) ===<br />
<br />
This statement pair is used to either store (--s) or load (--l) data from persistent storage. Items stored in persistent storage remain between card rolls and between Roll20 sessions. There are two types of data that can be stored: settings and roll variables. <br />
<br />
Examples:<br />
<br />
<pre><br />
--Ssettings|GreenStyle<br />
--Srollvariables|FirstCardVars<br />
</pre><br />
<br />
In this case, the tag for the statement determines what type of item is being saved (settings or rollvariables). When saving settings, all non-default settings are written to the named setting storage value. When Roll Variables are saved, all variables that currently exist will be saved to the named storage value.<br />
<br />
Loading stored items simply requires the same command with the --l statement type:<br />
<br />
<pre><br />
--Lsettings|GreenStyle<br />
--Lrollvariables|FirstCardVars<br />
</pre><br />
<br />
When loading settings, all stored settings will be applied to the current card settings. You can override settings by changing them after the load.<br />
<br />
When loading roll variables, the saved variables will be added to (or overwrite if they have the same name) any variables on the current card. This means it is safe to create roll variables before the load statement.<br />
<br />
'''Practical Uses'''<br />
The major intended use of persistent storage is for storing card formats for use in later scripts. For example, the following script:<br />
<br />
<pre><br />
!scriptcard {{<br />
--#titlecardbackground|#22CC22<br />
--#oddrowbackground|#cceecc<br />
--#evenrowbackground|#99ee99<br />
--Ssettings|@{selected|token_name}<br />
}}<br />
</pre><br />
<br />
Would save the titlecardbackground, oddrowbackground, and evenrowbackground settings to a saved list named after the selected token's name. When creating cards for that token to run later, you could include the line:<br />
<br />
<pre><br />
--Lsettings|@{selected|token_name}<br />
</pre><br />
<br />
To load all of the settings at once. By creating these setting sets for each character, you can specify a different color scheme for each character that can then be used in cards with a single formatting line.<br />
<br />
There is a supplemental ! command added to support saved settings:<br />
<br />
<pre><br />
!sc-liststoredsettings<br />
</pre><br />
<br />
Will produce a list of all stored setting names, with buttons to list the setting values stored in each group and a button to delete groups as needed.<br />
<br />
=== Visual Effects (--v) ===<br />
<br />
The --v statement can be used to create visual effects on the tabletop. The tag portion of the statement can be either "token" or "betweentokens". The content portion of the statement contains the required parameters for the effect generation, separated by spaces. If the effect is "none", no effect will be played. If any other value that doesn't match a Roll20 effect name will result in a burst-fire effect.<br />
<br />
For "token" effects, the parameters are the token id for the token the effect happens on, followed by the effect specifier.<br />
<br />
Example:<br />
<pre><br />
--vtoken|@{selected|token_id} burst-fire<br />
</pre><br />
<br />
For "betweentoken" effects, the parameters are the source token id, the target token id, and the effect specifier.<br />
<br />
Example:<br />
<pre><br />
--vbetweentokens|@{selected|token_id} @{target|token_id} beam-magic<br />
</pre><br />
<br />
'''''Version 1.2.8+'''''<br />
<br />
An additional effect specifier, "point" is available in 1.2.8+. This specifier allows you to create a visual effect at a designated X/Y pixel coordinate. Future updates will add custom-vfx support to this option. The parameters are the X and Y coordinates and the effect descriptor. As of version 1.2.9, you can also use custom effect specifiers with Point effects:<br />
<br />
<pre><br />
--vpoint|150 200 burst-fire<br />
</pre><br />
<br />
=== Echo to Chat (--e) ===<br />
<br />
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.<br />
<br />
Example:<br />
<pre><br />
--eThe Ghost|/em hovers around @{selected|character_name}... BOO!<br />
</pre><br />
<br />
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).<br />
<br />
'''''Whispering'''''<br />
<br />
You can use the echo statement to send a whisper, but there's a trick to it. If you execute this code here:<br />
<br />
<pre><br />
--eThe Ghost|/w ExamplePlayerName Boo.<br />
</pre><br />
<br />
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.<br />
<br />
So, in conclusion, it's best to use something like this when you're sending a whisper:<br />
<br />
<pre><br />
!script {{<br />
--#hidecard|1<br />
--&sender|The Ghost<br />
--&receiver|ExamplePlayerName<br />
--&message|Boo.<br />
--e[&sender]|/w [&receiver] [&message]<br />
--eScriptCards|/w gm **Whispered from [&sender] to [&receiver]:** [&message] <br />
}}<br />
</pre><br />
<br />
This will ensure that you see the message in your chat feed as well.<br />
<br />
=== Repeating Section Access (--R) ===<br />
<br />
ScriptCards (as of v0.0.13) supports accessing repeating section rows on a character sheet with the --R statement type. <br />
<br />
There are three basic commands you can use with --R, and they are specified by the tag used:<br />
<br />
<pre><br />
--Rfind|characterid;EntryName;SectionPrefix;SearchField<br />
</pre><br />
<br />
This is the most direct way to access a repeating section row. Supplying the character ID, followed by what you are looking for (Greatsword, for example), followed by the character sheet's section prefix (repeating_attack), followed by the field to check what you are searching for (atkname) will load the matching section (if found) into the script parsers memory. For example:<br />
<br />
<pre><br />
--Rfind|@{selected|character_id};Greatsword;repeating_attack;atkname<br />
</pre><br />
<br />
Will look at the character's "repeating_attack" section for an entry with an atkname value equal to "Greatsword". Similarly:<br />
<br />
<pre><br />
--Rfind|@{selected|character_id};Bite;repeating_npcaction;name<br />
</pre><br />
<br />
Will look for a "Bite" action on an NPC's action list.<br />
<br />
<pre><br />
--Rfirst|characterid;section prefix<br />
</pre><br />
<br />
This form of the --R command will look at all of the entries in the specified repeating section and load the first one into memory:<br />
<br />
<pre><br />
--Rfirst|@{selected|character_id};repeating_attack<br />
</pre><br />
<br />
Would load the character's first "repeating_attack" row into memory.<br />
<br />
<pre><br />
--Rnext|<br />
</pre><br />
<br />
No parameters are required for --Rnext, which loads the next entry in the list that was obtained with "first" into memory.<br />
<br />
However a row is obtained, it will be parsed to replace any attribute references (ie, @{level}) with the corresponding character attribute.<br />
<br />
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".<br />
<br />
You can reference repeating attribute data using the syntax [*R:attributename] syntax (similar to referencing standard character attributes).<br />
<br />
Here are some examples:<br />
<br />
Display the details of the "Greatsword" PC attack:<br />
<br />
<pre><br />
!script {{<br />
--Rfind|@{selected|character_id};Greatsword;repeating_attack;atkname<br />
--+Attack Name|[*R:atkname]<br />
--+Base Damage|[*R:dmgbase]<br />
}}<br />
</pre><br />
<br />
[[File:Scriptcards repeating greatsword.png|Repeating Greatsword Attack]]<br />
<br />
List all of the actions an NPC can take (just actions, not legendary, etc.)<br />
<br />
<pre><br />
!script {{<br />
--#title|NPC Actions<br />
--#leftsub|@{selected|token_name}<br />
--Rfirst|@{selected|character_id};repeating_npcaction<br />
--:DisplayLoop|<br />
--?"[*R:name]" -eq NoRepeatingAttributeLoaded|Done<br />
--+Action:|[*R:name] [*R:attack_damage] [*R:attack_damagetype]<br />
--?"[*R:attack_damage2]" -eq ""|NoSecondaryDamage<br />
--+ |[*R:attack_damage2] [*R:attack_damagetype2]<br />
--:NoSecondaryDamage|<br />
--Rnext|<br />
-->DisplayLoop| <br />
--:Done|<br />
}}<br />
</pre><br />
<br />
[[File:Scriptcards repeating npcactions.png]]<br />
<br />
In the script above, we get the "first" repeating_npcaction and display information about it. We then execute "next" and repeat until we run into "NoRepeatingAttributeLoaded".<br />
<br />
'''''Special debugging command: dump'''''<br />
<pre><br />
--Rdump|<br />
</pre><br />
<br />
The "dump" command will list all of the attributes ScriptCards knows about for the currently loaded repeating row to the API Console Log.<br />
<br />
=== Assign Variable to Built-In Function (--~) ===<br />
<br />
ScriptCards has the ability to run a function built into the API script and return the results to a variable. Some functions return roll variables, while others return strings. See the function table below for details. The format is:<br />
<br />
--~VariableName|function;param1;param2;param3;...<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Function Name !! Parameters !! Description<br />
|-<br />
| distance || token_A_ID;token_B_ID || Calculate the Chebyshev distance in grid units between two tokens. This is the measurement scheme D&D 4E/5E use for diagonal distance measurement<br />
|-<br />
| euclideandistance || token_A_ID;token_B_ID || Calculate the Euclidean distance between two tokens. This is essentially the Pythagorean theorem in action. Returns the result in grid units.<br />
|-<br />
| euclideanpixel || token_A_ID;token_B_ID || Calculate the Euclidean distance between two tokens and returns the result is pixels instead of grid units. <br />
|-<br />
| euclideanlong || token_A_ID;token_B_ID || 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 is calculated instead of before. More accurate over long distances. <br />
|-<br />
| manhattandistance || token_A_ID;token_B_ID || Also called "taxicabdistance" (which is an acceptable function name), this measures to how-many-over, how-many-up/down distance, disallowing diagonal movement.<br />
|-<br />
| getselected || none || 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 the first selected token, VariableName2 the second, etc.<br />
|}<br />
<br />
'''''Functions with Sub Functions'''''<br />
<br />
Most ScriptCards functions are grouped into set as sub functions. The table below lists the major functions and their sub functions.<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Function Name !! Sub Function !! Parameters !! Return Type !! Description<br />
|-<br />
| array || define || arrayname;value1;value2;... || none || Creates an array called "arrayname" and adds value1, value2, etc. to the array<br />
|-<br />
| array || sort || arrayname || none || Sorts the specified array in place in ascending order<br />
|-<br />
| array || add || arrayname;value1;value2;... || none || Adds value1, value2, ... to the existing array "arrayname"<br />
|-<br />
| array || remove || arrayname;value1;value2;... || none || Removes value1, value2, ... from the existing array "arrayname". Resets the array index to 0.<br />
|-<br />
| array || replace || arrayname;currentvalue;newvalue || none || Replaces all occurrences of "currentvalue" in "arayname" with "newvalue"<br />
|-<br />
| array || setatindex || arrayname;index;newvalue || none || Replaces the array item at index "index" with "newvalue"<br />
|-<br />
| array || getindex || arrayname || stringVariable || Retrieves the current index in "arrayname" and stores it in the supplied string variable<br />
|-<br />
| array || setindex || arrayname;newindex || none || Sets the current index in array "arrayname" to "newindex"<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| array || removeat || arrayname;indexposition || none || Removes the item at index "indexposition" from "arrayname". Resets the current array index to 0.<br />
|-<br />
| array || indexof || arrayname;searchvalue || stringVariable || Searches the array "arrayname" for and item with the value of "searchvalue" and, if found, returns the index of the first matching value or "ArrayError" if not found<br />
|-<br />
| array || getlength || arrayname || stringVariable || Returns the number of items in array "arrayname"<br />
|-<br />
| array || pagetokens || arrayname;tokenid;(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. 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.)<br />
|-<br />
| 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.<br />
|-<br />
| array || stringify || arrayname || stringVariable || Returns all of the items in "arrayname" as a string separated by semicolons (;)<br />
|-<br />
| array || fromstring || arrayname || delimiter;string || Creates an array from "string", splitting "string" on "delimiter" to separate the items<br />
|-<br />
| array || statusmarkers|| arrayname;tokenid || none|| Creates an array (arrayname) of the active statusmarkers (sometimes called Token Markers) for the specified tokenid<br />
|-<br />
| math || angle || math;angle;tokenid;tokenid|| rollVariable || Calculates the angle between two tokens and returns the value in degrees<br />
|-<br />
| math || ceil || math;ceil;value || rollVariable || Rounds '''value''' up to the next integer, dropping any decimal portion of the number<br />
|-<br />
| math || clamp || math;clamp;value;lowerBound;upperBound || rollVariable || Returns '''value''', but restricted to the range of '''loweBound''' and '''upperBound'''.<br />
|-<br />
| math || floor || math;floor;value || rollVariable || Rounds '''value''' down, dropping any decimal portion of the number<br />
|-<br />
| math || max || math;max;valueA;valueB || rollVariable || Returns the larger of '''valueA''' vs '''valueB'''<br />
|-<br />
| math || min || math;min;valueA;valueB || rollVariable || Returns the smaller of '''valueA''' vs '''valueB'''<br />
|-<br />
| math || round || math;round;value || rollVariable || Rounds '''value''' to the nearest integer<br />
|-<br />
| string || length || string;length;stringValue || rollVariable || Returns the length of '''stringValue''' in characters<br />
|-<br />
| string || before || string;before;searchText;stringValue || stringVariable || Searches '''stringValue''' for '''searchText''' and returns the portion of '''stringValue''' prior to that text<br />
|-<br />
| string || after || string;after;searchText;stringValue || stringVariable || Searches '''stringValue''' for '''searchText''' and returns the portion of '''stringValue''' after that text<br />
|-<br />
| string || left || string;left;count;stringValue || stringVariable || Returns the leftmost '''count''' characters of '''stringValue'''<br />
|-<br />
| string || right || string;right;count;stringValue || stringVariable || Returns the rightmost '''count''' characters of '''stringValue'''<br />
|-<br />
| string || replace || string;replace;searchText;replaceText;stringValue || stringVariable || Replaces '''searchText''' in '''stringValue''' with '''replaceText''' and returns the resulting string<br />
|-<br />
| string || replaceall || string;replace;searchText;replaceText;stringValue || stringVariable || Replaces all intances of '''searchText''' in '''stringValue''' with '''replaceText''' and returns the resulting string '''''Requires 1.2.9+'''''<br />
|-<br />
| string || trim || string;trim;stringValue || stringVariable || Removes leading and trailing spaces from stringValue and returns the result. <br />
|-<br />
| string || substring || string;substring;start;count;stringValue || stringVariable || Returns '''count''' characters starting at '''start''' from '''stringValue'''<br />
|-<br />
| 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.<br />
|-<br />
| string || tolowercase || string;tolowercase;stringValue || stringVariable || Converts the passed string to lower case and assigns to the passed variable name. <br />
|-<br />
| string || touppercase || string || stringVariable || Converts the passed string to upper case and assigns to the passed variable name. <br />
|-<br />
| 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. <br />
|-<br />
| 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.<br />
|-<br />
| 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'''.<br />
|-<br />
| turnorder || clear || none || none || Clears all entries from the {{Turn Tracker}}/Initiative<br />
|-<br />
| turnorder || addtoken || tokenid;trackervalue || none || Adds the token represented by "tokenid" to the initiative tracker with an initiavie value of "trackervalue"<br />
|-<br />
| turnorder || replacetoken || tokenid;trackervalue || none || Replaces the token represented by "tokenid" in the initiative tracker with an initiavie value of "trackervalue". Will add the token if it doesn't exist in the tracker.<br />
|-<br />
| turnorder || removetoken || tokenid || none || Removes the token represented by "tokenid" from the initiative tracker if it exists<br />
|-<br />
| turnorder || addcustom || textlabel;trackervalue || none || Add a custom text entry to the {{Turn Tracker}}/Initiative named "textlabel" with an initiative value of "trackervalue"<br />
|-<br />
| system || date || getdatetime || stringVariable || Returns the date time in the active timezone (see settings) <br />
|-<br />
| system || date || getdate || stringVariable || Returns the date in the active timezone (see settings) <br />
|-<br />
| system || date || gettime || stringVariable || Returns the time in the active timezone (see settings)<br />
|-<br />
| system || dumpvariables || "rolls", "string", or "array" || none || Dumps all of the defined variables of the indicated type to the console log<br />
|-<br />
| system || findability || system;findability;charactername;abilityname || stringVariable || Returns the object ID of the ability on the indicated character or "AbilityNotFound"<br />
|-<br />
|}<br />
<br />
Examples:<br />
<br />
<pre><br />
--~HowFarAway|distance;@{selected|token_id};@{target|token_id}<br />
</pre><br />
<br />
Returns the distance (Chebyshev) between the selected and target tokens and stores it in "HowFarAway".<br />
<br />
<pre><br />
--SelectedDudes|getselected<br />
</pre><br />
<br />
If 5 tokens were selected, 6 variables would be created: SelectedDudesCount (with a value of 5), SelectedDudes1, SelectedDudes2, SelectedDudes3, SelectedDudes4, SelectedDudes5.<br />
<br />
=== Information Request (--i) ===<br />
<br />
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.<br />
<br />
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.<br />
<br />
After the user has clicked the button and responded to the requests, ScriptCards will resume processing the script from where it left off.<br />
<br />
Here is an example “i” line:<br />
<br />
<pre><br />
--IScriptCards needs additional information to continue;Click to select a target and provide information|t;MyNewTarget;Missile1Target||q;MyNameIs;What is your name?<br />
</pre><br />
<br />
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.<br />
<br />
Supported information request types are “t” for target token, and “q” for query.<br />
<br />
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).<br />
<br />
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:<br />
<br />
<pre><br />
q;UserName;What is your name?|Fred|Bob|Sally|Nancy<br />
</pre><br />
<br />
Would have a dropdown menu with four choices.<br />
<br />
== Inline Formatting ==<br />
<br />
Inline formatting is processed on Direct Output lines only (--+ lines) and the following inline format markup is available:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Formatting Tags !! Description<br />
|-<br />
| [b]..[/b] || Bold the text between the markers <br />
|-<br />
| [i]..[/i] || Italicize the text between the markers <br />
|-<br />
| [u]..[/u] || Underline the text between the markers <br />
|-<br />
| [s]..[/s] || Strike-Thru the text between the markers <br />
|-<br />
| [c]..[/c] || Center alignment <br />
|-<br />
| [l]..[/l] || Left alignment <br />
|-<br />
| [r]..[/r] || Right alignment <br />
|-<br />
| [j]..[/j] || Full justification alignment <br />
|-<br />
| [#xxx]..[/#] or [#xxxxxx]..[/#] || Use a 3 or 6 digit hex code to colorize the text between the markers <br />
|-<br />
| [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, <code>[img width=128 height=128]</code> )<br />
|-<br />
| [button]caption::action[/button] || Create a button with the label "caption" that performs the action defined by "action". <br />
|-<br />
| [t] || Converted to HTML table tag. Text after the "t" will be included inside the tag (width, border, etc)<br />
|-<br />
| [/t] || Converted to HTML close table tag.<br />
|-<br />
| [tr] || Converted to HTML table row tag. Text after the "tr" will be included inside the tag<br />
|-<br />
| [/tr] || Converted to HTML close table row tag.<br />
|-<br />
| [td] || Converted to HTML table cell tag. Text after the "tr" will be included inside the tag<br />
|-<br />
| [/td] || Converted to HTML close table cell tag.<br />
|}<br />
<br />
== Variables ==<br />
<br />
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. While it is possible to assign both a string and a roll variable the same name, doing so will likely result in confusion when looking at the script later, so it is not recommended.<br />
<br />
String Variables are assigned with the --& statement and are referenced using [&variableName] notation.<br />
<br />
Roll Variables are assigned with the --= statement, and the assignment value is always processed by the ScriptCards Roll Processor (resolves dice rolls, etc.)<br />
<br />
There are a handful of variables assigned automatically when a ScriptCard is executed. These are all string variables, and are:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Variable !! Value<br />
|-<br />
| SendingPlayerID || Contains the object ID of the player that sent the macro<br />
|-<br />
| SendingPlayerName || Contains the display name of the player<br />
|-<br />
| SendingPlayerColor || Contains the color code associated with the player<br />
|-<br />
| SendingPlayerSpeakingAs || The contents of the "Speaking As" dropdown window<br />
|-<br />
| SendingPlayerIsGM || Contains 1 if the player is a GM, and 0 if the player is NOT a GM<br />
|}<br />
<br />
== Arrays ==<br />
<br />
Arrays are a special type of variable, and are managed by the function (<nowiki>--~</nowiki> command). All of the array function commands follow the same pattern:<br />
<br />
<pre>--~variableName|array;subcommand;arrayname;param1;param2;param3;...</pre><br />
<br />
Not all array commands return anything to "variableName". The function table above will specify the return type of the command if any.<br />
<br />
There are a couple of different ways to create an array:<br />
<br />
The '''define''' array subcommand creates (or recreates) an array and assigns it values - one for each included parameter after the array name. For example:<br />
<br />
<pre>--~|array;define;Fruits;mango;peach;strawberry;apricot;banana;apple</pre><br />
<br />
will create an array called '''Fruits''' with 6 elements in the order listed in the command (mango, peach, etc.)<br />
<br />
You can also use two other subcommands to create arrays based on tokens:<br />
<br />
<pre>--~Count|array;pagetokens;Everybondy;@{selected|token_id}</pre><br />
<br />
and<br />
<br />
<pre>--~Count|array;selectedtokens;Selected</pre><br />
<br />
In both cases, arrays of tokens will be created, and a string variable called "Count" will be set to the number of tokens in the array. The '''pagetokens''' command returns (by default) all of the tokens on the page that contains the token passed as the parameter after the array name. You can filter the tokens that "pagetokens" includes in the array by appending an optional parameter describing the type of token you are looking for:<br />
<br />
<pre>--~Count|array;pagetokens;Everybondy;@{selected|token_id};npc</pre><br />
<br />
Will return only tokens on the page that represent characters that do not have a ''controlledby'' parameter set. The available options are "all" (default), "char", "graphic", "pc", and "npc".<br />
<br />
The '''selectedtokens''' command returns an array with all of the tokens that were selected when the script was called.<br />
<br />
You can also use an arbitrary string to create an array, specifying a delimiter with the '''fromstring''' command:<br />
<br />
<pre><br />
--&names|Fred<br />
--&names|+,Sally<br />
--&names|+,Ted<br />
--&names|+,Joyce<br />
--~|array;fromstring;,;[&names]<br />
</pre><br />
<br />
The above example builds a comma-separated string and then uses "fromstring" to create an array with 4 elements from it, specifying the comma as the delimiter.<br />
<br />
Finally, you can use the '''statusmarkers''' command to create an array with one entry for each active status marker on a specified token:<br />
<br />
<pre>--~|array;statusmarkers;Conditions;@{selected|token_id}</pre><br />
<br />
will create an array with one entry for each status active on the selected token. The array elements will be the internal name of the status (if you are using custom status marker packs, the names will be specified in the marker pack).<br />
<br />
'''Traversing Arrays'''<br />
<br />
Each array keeps track of an internal index position (starting at 0). Several commands let you manage this index:<br />
<br />
*'''getindex''' returns the current index value<br />
*'''setindex''' sets the index to the specified location in the array<br />
*'''getlength''' returns the number of elements in the array<br />
*'''indexof''' returns the index location of the specified element<br />
<br />
Other commands let you retrieve values from the array:<br />
<br />
*'''getfirst''' sets the index to 0 and returns the value at that position<br />
*'''getnext''' advances the index by 1 and returns the new current value<br />
*'''getprevious''' reduces the index by 1 and returns the new current value<br />
*'''getlast''' sets the index to the last elements in the array and returns the new current value<br />
<br />
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.<br />
<br />
'''Manipulating Array Elements'''<br />
<br />
Several array commands deal with inserting, removing, and modifying elements:<br />
<br />
*'''add''' works just like define, except that it takes an existing array and adds elements to it based on the passed parameters<br />
*'''remove''' looks for items matching each passed parameter and removes them from the indicated array if they exist<br />
*'''removeat''' allows you to specify an index location in the array and remove the element at that position<br />
*'''replace''' searches an array for a value and replaces all occurrences of it with a new value (if found)<br />
*'''sort''' sorts the elements in the array in ascending order<br />
*'''strinfigy''' returns a string variable that includes each array element separated by semicolons (;) <br />
<br />
'''Referencing Array Elements'''<br />
<br />
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.<br />
<br />
<pre><br />
!script {{<br />
--~dummy|array;pagetokens;myarray;@{selected|token_id}<br />
--~count|array;getcount;myarray<br />
--+Total:|There are [&count] graphical objects on the page<br />
--~testvar|array;getfirst;myarray<br />
--:loop|<br />
--+Value|[*[&testvar]:character_name]<br />
--~testvar|array;getnext;myarray<br />
--?[&testvar] -ne ArrayError|loop<br />
--+Loop1|Is Done!<br />
}}<br />
</pre><br />
<br />
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:<br />
<br />
<pre><br />
!script {{<br />
--~dummy|array;pagetokens;myarray;@{selected|token_id}<br />
--~count|array;getcount;myarray<br />
--+Total:|There are [&count] graphical objects on the page<br />
--%loopCounter|1;[&count]<br />
--+Value|[*[@myarray([&loopCounter])]:character_name]<br />
--%|<br />
--+Loop|Is Done!<br />
}}<br />
</pre><br />
<br />
This line : <nowiki>--+Value|[*[@myarray([&loopCounter])]:character_name]</nowiki> uses [@arrayName(index)] format (inside a [*characterid:attribute] syntax) to perform the same task as running through the loop with the index.<br />
<br />
(Note: Additional examples are on the way...)<br />
<br />
== For...Next Loops ==<br />
<br />
For...Next loops in ScriptCards are supported with the with the --% statement type. A loop is defined by starting off with:<br />
<br />
<pre><br />
--%LoopCounter|<start>;<end>;[step]<br />
</pre><br />
<br />
The start and end values are required, while the step parameter is optional. If the step is omitted, it will be assumed to be 1. A string variable named after the line tag ("LoopCounter" in the case above) will be created and will hold the current iteration value for the loop. Here is a real example:<br />
<br />
<pre><br />
--%LoopCounter|1;10;1<br />
</pre><br />
<br />
This will begin a loop identified by "LoopCounter" that will start at 1, increasing by 1 each iteration (the step) until it has completed 10 executions.<br />
<br />
The "next" statement is simply <code>--%|</code>, with no tag or parameters. This indicates to ScriptCards that it should increment the counter and go back to the beginning of the loop. Extending the example above:<br />
<br />
<pre><br />
!script {{<br />
--%LoopCounter|1;10;1<br />
--=Roll|1d20<br />
--+Loop|Counter is [&LoopCounter], roll was [$Roll]<br />
--%|<br />
}}<br />
</pre><br />
<br />
The <code>--%!|</code> sequence will break out of the loop, no matter how many iterations are remaining.<br />
<br />
The % and %! character sequences can also be used as part of a 1.2.1+ non-branching conditional to continue or break the loop:<br />
<br />
<pre><br />
--?"X[&RollInto]X" -eq "XX"|%<br />
</pre><br />
<br />
In this example, if the string variable RollInfo is empty, the loop will return to the top and continue with the next iteration, while:<br />
<br />
<pre><br />
--?"X[&RollInto]X" -eq "XX"|%!<br />
</pre><br />
<br />
Would cause the whole loop to end if the condition were true.<br />
<br />
== Referencing ==<br />
<br />
=== Roll Variables===<br />
<br />
Roll Variables can be referenced from the content portion of any line type, and from the tag portion of conditional statements. The referenced value is replaced when the line is executed.<br />
<br />
There are several modifiers that can be used to reference parts of a roll:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Modifier !! Meaning<br />
|-<br />
| No modifier || In a Direct Output Line (<nowiki>--+</nowiki>), GM Output Line (<nowiki>--*</nowiki>), or String Assignement (<nowiki>--&</nowiki>), 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<br />
|-<br />
| .Total || The end result of the roll equation. Formatting rules for "No Modifier" apply based on line type. <br />
|-<br />
| .Raw || The total value of the roll variable without any formatting, no matter what kind of line the reference is used in.<br />
|-<br />
| .Base || The cumulative result of any dice rolled in the Roll Text (Numeric modifiers are not included) <br />
|-<br />
| .Ones || The number of dice in the roll that came up as 1s <br />
|-<br />
| .Aces || The number of dice in the roll that came up as the maximum number on the die <br />
|-<br />
| .Odds || The number of dice in the roll that came up with an odd number <br />
|-<br />
| .Evens || The number of dice in the roll that came up with an even number <br />
|-<br />
| .RollText || The raw text of the roll that was use to generate the results <br />
|-<br />
| .Text || A text representation of the results of the roll, including the numbers rolled for each die <br />
|-<br />
| .tableEntryText || The text portion of the result of a table roll<br />
|-<br />
| .tableEntryImgURL || The image source portion of the result of a table roll<br />
|-<br />
| .tableEntryValue || If the tableEntryText is purely numeric, will contain the numeric value<br />
|}<br />
<br />
=== String Variables ===<br />
<br />
To reference a string variable, use the notation [&variablename]. String variables can be referenced in direct output, roll variable assignment, and string variable assignment statements.<br />
<br />
=== Character/Token Attributes ===<br />
<br />
A character or token attribute can be referenced from content portion of any type of line and is substituted when the line is executed. The general format for referencing a character attribute is [*ID:attribute]. ID can be a token ID or a character ID (these start with a dash). Additionally if you have specified a sourceToken or targetToken, you can substitute "S" or "T" for the ID (for example [*S:npc_type] will retrieve the npc_type attribute from the source token.<br />
<br />
By default, all attribute references will be pulled from the '''''character''''' object that the ID represents (either directly or by being a Token ID that represents a character).<br />
<br />
Keep in mind, that if you want to access the "max" of a character attribute (for example, the max hit points), then you cannot trust the name that your roll20 character sheet shows you when you hover your mouse over the max hit points. For example, this reference will not work: [*S:hp_max]. Instead, you need to use this reference: [*S:hp^].<br />
<br />
If your ID refers to a token, token attributes can be accessed by preceding the attribute name with "t-", for example [*S:t-aura1_radius]. Supported token attributes are:<br />
<br />
{|<br />
| t-name || t-id || t-statusmarkers || t-bar1_value<br />
|-<br />
| t-bar1_max || t-bar2_value || t-bar2_max || t-bar3_value<br />
|-<br />
| t-bar3_max || t-top || t-left || t-width<br />
|-<br />
| t-height || t-rotation || t-layer || t-aura1_radius<br />
|-<br />
| t-aura1_color || t-aura2_radius || t-aura2_color || t-aura1_square<br />
|-<br />
| t-aura2_square || t-tint_color || t-light_radius || t-light_dimradius<br />
|-<br />
| t-light_angle || t-light_losangle || t-light_multiplier || t-light_otherplayers<br />
|-<br />
| t-light_hassight || t-flipv || t-fliph || t-controlledby<br />
|-<br />
| t-_cardid || t-_pageid || t-imgsrc || t-bar1_link<br />
|-<br />
| t-bar2_link || t-bar3_link || t-represents || t-layer<br />
|-<br />
| t-isdrawing || t-name || t-gmnotes || t-showname<br />
|-<br />
| t-showplayers_name || t-showplayers_bar1 || t-showplayers_bar2 || t-showplayers_bar3<br />
|-<br />
| t-showplayers_aura1 || t-showplayers_aura2 || t-playersedit_name || t-playersedit_bar1<br />
|-<br />
| t-playersedit_bar2 || t-playersedit_bar3 || t-playersedit_aura1 || t-playersedit_aura2<br />
|-<br />
| t-lastmove || t-adv_fow_view_distance || t-has_bright_light_vision || t-has_night_vision<br />
|-<br />
| t-night_vision_distance || t-emits_bright_light || t-bright_light_distance || t-emits_low_light<br />
|-<br />
| t-low_light_distance || t-has_limit_field_of_vision || t-limit_field_of_vision_center || t-limit_field_of_vision_total<br />
|-<br />
| t-has_limit_field_of_night_vision || t-limit_field_of_night_vision_center || t-limit_field_of_night_vision_total || t-has_directional_bright_light<br />
|-<br />
| t-directional_bright_light_center || t-directional_bright_light_total || t-has_directional_dim_light || t-directional_dim_light_center<br />
|-<br />
| t-directional_dim_light_total || t-lightColor || || |<br />
|}<br />
<br />
'''''It is important to note that some attributes names on tokens have corresponding attribute names on characters, which represent different values. For example, [*T:id] returns the character ID, while [*T:t-id] returns the token ID.'''''<br />
<br />
=== Subroutine Parameters ===<br />
<br />
When using a gosub statement (-->) or a conditional marked as a gosub (prefixing the label with a > character), you can pass any number of parameters separated by semicolons (;) that the code in the subroutine can utilize.<br />
<br />
Subroutine parameters are numbered starting at 1, and are accessed by using the notation [%number%], so the first parameter is [%1%], the second is [%2%], etc.<br />
<br />
Parameter substitution happens on all line types, and happens prior to character attribute references or roll variable substitution.<br />
<br />
=== Campaign Attribute ===<br />
You can retrieve properties of the API's Campaign object with the [*C:attributename] syntax. For example, [*C:playerpageid] will retrieve the current player ribbon page from the Campaign object.<br />
<br />
=== Page Attributes ===<br />
If you have set the '''activepage''' parameter, you can retrieve page-related properties with the [*P:attributename] syntax, including the page's UDL parameters.<br />
<br />
=== Repeating Section Values ===<br />
<br />
You can reference repeating attribute data using the syntax [*R:attributename] syntax (similar to referencing standard character attributes). The currently active repeating row information will be used to retrieve attribute values. You can also retrieve the full attribute name for a repeating row attribute by using the [*R>attributename] notation. This is useful to pass to things like chatsetattr.<br />
<br />
=== Array Elements ===<br />
After an array has been declared, the elements can be referenced with [@arrayName(index)]. Array indices start at 0.<br />
<br />
== Deferred Resolution for Meta Scripts ==<br />
<br />
As of 1.2.9, ScriptCards supports a deferral character for use when calling another API script with via the --@ statement, to defer processing of meta script references so they get processed prior to the sub-API call insted of prior to ScriptCards execution. To defer this processing for meta script (SelectManager, Fetch) by inserting a deferral character into the meta call. For example, if I want to have ScriptCards call TokenMod as if the token for "Quej Gr'stra" (yes, I let Roll20 name my test NPCs) I could use something like this:<br />
<br />
--@token-mod|{^& select Quej Gr'stra} _on showname<br />
<br />
The "^" in between { and & will prevent SelectManager from seeing the call when the ScriptCard script is processed, but the --@ statement will remove the deferral character so the command that will be sent by ScriptCards is:<br />
<br />
!token-mod {& select Quej Gr'stra} --on showname<br />
<br />
With the deferral character removed, SelectManager will see the {& select ...} and do its magic.<br />
<br />
While the default deferral character is "^", the deferral character is a setting that can be changed:<br />
<br />
--#deferralcharacter|%<br />
<br />
Will make % the deferral character for future --@ statements in the running script.<br />
<br />
There are currently three supported Meta script structures: {^&...} for SelectManager, @^(...) and *^(...) for fetch, where the ^ in the structures here represents the placement of the deferral character.<br />
<br />
== Arrays ==<br />
<br />
Arrays are a new data type introduced in version 1.1.12 of ScriptCards, and are manipulated with associated function (--~) commands.<br />
<br />
* Arrays are a lists of strings. Items in an array cannot contain the semi-colon (;) character, as that is used to separate parameters in the function code that deals with arrays.<br />
* Arrays are accessed via the --~ script command. In some cases, the value of the tag (variable name) for array commands is not used, and can be a dummy value or simply omitted. I have omitted them in the statements below.<br />
* All commands that DO return a value return string values, even if the content is numeric.<br />
* If a command returns a value and there is some sort of reason that it isn't an array value, you will get "ArrayError" in the return value. This can happen if you reach the end of an array while stepping through it, for example, so checking for "ArrayError" can serve as the end condition for a loop.<br />
* Each array keeps track of its current index, allowing you to step forward and backwards through arrays.<br />
* Any number of arrays can be defined.<br />
* Unlike string variables and roll variables, array variables cannot (currently) be referenced directly. It is necessary to use the function (--~) syntax to manipulate arrays and get values from them as strings for use in other parts of your script.<br />
<br />
<br />
== Reentrant Scripts ==<br />
<br />
Reentrant scripts allow you to create buttons in your script code that will re-execute the script at a given label within the code. If you set the reentrant setting (--#reentrant|somevalue) to a non-zero value, your setting and variable information will be preserved between executions. Reentrant script can be used to present menus or choices and then continue acting.<br />
<br />
Reentrant buttons are created with the [rbutton]Caption::ReentryLabel;Parameter[/rbutton] construct. The caption will be displayed on the generated button. ReentryLabel is the name of a label in your script that the button will jump to when clicked, and Parameter will be passed in as a string value called "reentryval".<br />
<br />
Example:<br />
<pre><br />
!script {{<br />
--#reentrant|testing<br />
--=Roll|1d20<br />
--+Roll|[$Roll]<br />
--&String|That was a [$Roll.Raw]!<br />
--~x|array;define;MyArray;Apple;Banana;Orange<br />
--+Try it|[rbutton]Hello!::EXEC_PC_SPELL;9[/rbutton]<br />
--X|<br />
<br />
--:EXEC_PC_SPELL|<br />
--+ReentryVal|[&reentryval]<br />
--+The value of Roll is|[$Roll]<br />
--+Value of String|[&String]<br />
--+Array|[@MyArray(0)]<br />
--X|<br />
}}<br />
</pre><br />
<br />
This script sets up some variables and then displays a button labeled "Hello!". If the user clicks the button, the script will be re-entered starting at the "EXEC_PC_SPELL", which will display the content of the variables from the original execution.<br />
<br />
'''''Note: This section needs to be expanded upon'''''<br />
<br />
== Procedure Libraries ==<br />
<br />
You can now create handouts in your game in Roll 20 with the name format "ScriptCards Library NAME", where name is a name you assign to the library. Library names are case sensitive. It is my hope that the more proficient ScriptCards scripters out there will provide procedure libraries (or procedures that can be included in libraries) for others to use to make their scripting life easier. Be they specific to a game system, or to a type of activity, I think a robust set of libraries that GMs could use to enhance their scripting capabilities would be very valuable to the community. Should such things begin to emerge, I’ll create a portion of the ScriptCards Wiki page to house them.<br />
<br />
To include one or more libraries in a script, use the +++libname+++ directive (does not need a -- line associated with it). Multiple library names can be specified by separating them with semicolons (i.e., +++General;dnd5elib;Colorize+++ would include three libraries (General, dnd5elib, and Colorize).<br />
<br />
Included libraries are separated from the main script code by the automatic inclusion of "--X|" before the first library is appended to the script, and all libraries are loaded at the end of the script before script processing takes place.<br />
<br />
Procedures and labels in libraries can be used just as if they were included in the body of your script. Note that this DOES mean that you could, technically, jump into a library with a direct branch (--^) or direct branch conditional, but I recommend using libraries to store reusable procedures.<br />
The Notes section of the library handout stores the library code, and is written just like any other ScriptCards code except:<br />
<br />
* They cannot use roll queries (?{Some Prompt:}) to get information from the user at execution time.<br />
* They cannot use @{} notation to access character and token information.<br />
<br />
Both of these limitation stem from the fact that Procedure Libraries are not processed by the chat server, which is what handles these items.<br />
<br />
Here is an example of handling damage modifications (resistance, vulnerability, and immunity) in D&D 5E with a library:<br />
<br />
<pre><br />
!script {{<br />
+++dnd5elib+++<br />
--#|Damage Modifiers Test<br />
--#targettoken|@{target|token_id}<br />
-->Lib5E_CheckDamageModifiers|ResistType;fire<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] fire damage<br />
<br />
-->Lib5E_CheckDamageModifiers|ResistType;cold<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] cold damage<br />
<br />
-->Lib5E_CheckDamageModifiers|ResistType;poison<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] poison damage<br />
<br />
-->Lib5E_CheckDamageModifiers|ResistType;acid<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] acid damage<br />
<br />
--X|<br />
}}<br />
</pre><br />
<br />
Library content (In a handout called “ScriptCards Library dnd5elib” NOTE: Paste into Notepad first and then paste into the handout in Roll20 to avoid bringing over HTML formatting from the web site):<br />
<br />
<pre><br />
--/|ScriptCards Library: dnd5elib version 0.0.1<br />
--/|Provides various utility procedures for D&D 5E games<br />
<br />
--/|Lib5E_CheckDamageModifiers handle damage resistance, vulnerability, and immunity. <br />
--/|Pass a string variable to be filled with a string to be appended to a dice roll and the damage type <br />
<br />
--:Lib5E_CheckDamageModifiers|damageVariableName;damageType<br />
--&[%1%]|<br />
--?"[*T:npc_vulnerabilities]" -inc "[%2%]"|>_Lib5E_IsVulnerable;[%1%]<br />
--?"[*T:npc_resistances]" -inc "[%2%]"|>_Lib5E_IsResistant;[%1%]<br />
--?"[*T:npc_immunities]" -inc "[%2%]"|>_Lib5E_IsImmune;[%1%]<br />
--<|<br />
<br />
--:_Lib5E_IsVulnerable| --&[%1%]| * 2 [Vulnerable] --<|<br />
--:_Lib5E_IsResistant| --&[%1%]| \ 2 [Resistant] --<|<br />
--:_Lib5E_IsImmune| --&[%1%]| * 0 [Immune] --<|<br />
</pre><br />
<br />
The idea is that the functions in the library create a string that can be appended to a roll to modify the output based on resistances, so you pass Lib5E_CheckDamageModifiers the name of the string variable you want to use and the damage type. The variable (ResistType in this case) will include either nothing, “* 2 [Vulnerable]”, “\ 2 [Resistant]”, or “* 0 [Immune]” which can be included in a roll assignment (--=) to modify the damage as appropriate. The order here might be important if an NPC is misconfigured to be both resistant and immune to the same damage type. Since immune is an absolute, having it last ensures that it will override resistant or vulnerable. A creature that is both vulnerable and resistant (again, misconfigured) will come back as resistant since that condition is checked after vulnerable.<br />
Some notes: I prefix my library labels with either “Lib5E_” or “_Lib5E_” as a clarity convention. This isn’t strictly necessary but you should be aware that if two libraries (or if your script and a library) define the same label, the last label defined will win. Since libraries are appended to the end of the script in the order you include them in the +++libname+++ directive, you can somewhat control this, but it is probably best to avoid re-declaring labels. <br />
<br />
In my case, items beginning with “Lib5E_” are intended to be called by scripts, while items beginning with “_Lib5E_” are intended to be used as subroutines by the “public” procedures. Of course, there is no reason you couldn’t call them directly.<br />
<br />
You might also note that I’ve included some library information in comment lines (--/|) at the top of the library. These are ignored by ScriptCards, and are a good way to convey requirements, parameters, usage information, etc.<br />
<br />
== Example Libraries ==<br />
<br />
=== dnd5elib ===<br />
<br />
[https://github.com/kjaegers/ScriptCards Download the dnd5elib Library from the ScriptCards GitHub]<br />
<br />
The '''dnd5elib''' library provides a collection of utility procedures that help simplify dealing with the D&D 5E Official Sheet. Some of the procedures in this library require '''chatsetattr''' to be installed in your game. This is a growing library, and currently only has a handful of routines. They are:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Procedure Name !! Notes<br />
|-<br />
| style="white-space:nowrap" | Lib5E_CheckDamageModifiers || This procedure can be used to evaluate vulnerabilities, resistances, and invulnerabilities on an NPC. After setting the --#target| parameters, pass the Lib5E_CheckDamageModifiers procedure a variable name (no reference information) and a damage type (i.e., fire, cold, bludgeoning, etc.) and a string variable with the name passed in as the first parameter will be created that contains text that can be included in a roll line (--=) in order to modify the roll as appropriate. For example, '''-->Lib5E_CheckDamageModifiers|ResistType;fire''' will check the current target character's attributes for "fire" and will either return an empty string (no references), "* 0 [Immune]" if the creature is immune, "\ 2 [Resistant]" if the creature is resistant, or "* 2 [Vulnerable]" if the creature is vulnerable to fire damage.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_DeductSpellSlot || Pass in a character_id and a slot level, and the script will expend one spell slot of that level, capping the value at 0 slots remaining. For Example '''<nowiki>-->Lib5E_DeductSpellSlot|@{selected|character_id};1</nowiki>''' to deduct a first level spell slot from the selected character.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_FindResource || Used to locate a resource value on a character. Pass in a character_id, a resource name, and two variable names. The procedure will check both repeating and non-repeating resources looking for a resource whose name matches what was passed in and return three variables. The first will be a string variable named for the 3rd parameter and contains the attribute name of the resource's "name" field. The second will be a string variable named after parameter 4 and contains the resource's value field attribute name, and the third variable is a Roll Variable, also named after the 4th parameter that contains the current resource value. Example: '''<nowiki>-->Lib5E_FindResource|@{selected|character_id};Crossbow bolts;ResName;ResValue</nowiki>''' will find "Crossbow bolts" as a resource on the character and return [&ResName] which is the name of the resource attribute, [&ResValue] which is the '''name of the attribute that stores the value''' and [$ResValue] which is the current numeric value of the resource.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Global_Attack_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Attack Modifiers (repeating_tohitmod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Bless" for 1d4 active and "Being Cool" for +2 active, I will get a return string " + 1d4 [Bless] + 2 [Being Cool]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Save_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Save Modifiers (repeating_savemod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Bless" for 1d4 active and "Being Cool" for +2 active, I will get a return string " + 1d4 [Bless] + 2 [Being Cool]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Skill_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Skill Modifiers (repeating_skillmod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Guidance" for 1d4 active and "Being Cool" for +2 active, I will get a return string " + 1d4 [Guidance] + 2 [Being Cool]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_AC_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Save Modifiers (repeating_savemod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Shield of Faith" with a value of 2 active, I will get a return string " + 2 [Shield of Faith]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Damage_Modifiers || Pass a character ID and TWO string variable to set the return value. The first string will be for normal damage, and the second will be the additional damage on a crit. This procedure will look through the Global Damage Modifiers (repeating_damagemod_*) for rows that are active (checked on the character sheet) and return two strings with the dice rolls and descriptions for them (for example, if I have "Sneak Attack" with a value of 1d6 normal and 1d6 critical damage active, I will get a return string " + 1d6 [Sneak Attack]" and another string of " + 1d6 [Sneak Attack CRIT]" that can be used in a dice rolls.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_DivineSmiteDice || Used to calculate the number of dice to be rolled for a paladin's Divine Smite. Pass a target token id, a spell slot level, and a string variable to be set to the dice roll amount based on the NPC_TYPE attribute of the target token. The returned variable will contain a dice roll (like "3d8" that can be used in a --= line)<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Character_Summary || Outputs a mini character sheet, including clickable buttons for attacks, actions, legendary actions, etc. Will automatically detect a PC vs NPC and output the appropriate sections.<br />
|}<br />
<br />
Due to formatting issues with the Wiki, the library code has been moved to a [https://gist.github.com/kjaegers/52f6049ddd257f0a1288aca4bbde13c5 GITHUB GIT]. Please view the GIST in raw mode and copy the text and paste it into a handout called "ScriptCards Library dnd5elib" in your Roll20 Game.<br />
<br />
== What to Know if you are Coming from PowerCards ==<br />
<br />
''Note: This section is a work in progress.''<br />
<br />
While ScriptCards and PowerCard have very similar output goals, their internals and use are quite different. The table below summarizes some of the major differences between the scripts.<br />
<br />
::{| class="wikitable"<br />
|-<br />
! PowerCards !! ScriptCards <br />
|-<br />
| With a handful of exceptions, all lines in a PowerCard macro are intended to produce a line of output on the final card. || With ScriptCards, ONLY the <code>--+</code> and <code>--*</code> statement types produces output <br />
|-<br />
| PowerCards lines begin with two dashes (<code>--</code>) followed by a unique tag name for the line, followed by a vertical bar and the content for the line. || ScriptCards lines begin with two dashes (<code>--</code>) followed by a '''statement type identifier''', which is a single character that identifies the type of line to the interpreter. This is followed by a tag (frequently optional), a vertical bar, and the parameters for the statement being executed.<br />
|-<br />
| PowerCard macros are always processed top to bottom. Lines can be hidden so they don't output anything, but there is no looping or branching (--SkipTo looks like a branch, but it just hides all of the lines until the referenced label. || ScriptCards scripts support true branching, including direct branching (<code>--^</code>) and procedure branching (<code>--></code>) and (<code>--<</code>). Procedures support parameters and a call stack so procedures can be nested to call other procedures.<br />
|-<br />
| All lines in a PowerCards macro need to have unique tags because PowerCards builds the card as a single JavaScript object using the tag names to store what will be displayed. This is why repeated tag names always result in the last one being shown. || ScriptCards tags do not need to be unique, and in the case of many line types are optional.<br />
|-<br />
| PowerCards conditionals result in either showing or hiding the line they are on. || ScriptCards conditionals '''''only''''' support branching as the result of the comparison. This branching can be direct (a GOTO) or procedural (a GOSUB) '''''NOTE: As of version 1.2.0, ScriptCards also supports roll/string variable assignment as a result of conditional evaluation'''''<br />
|-<br />
| PowerCards relies on the Roll20 [[Quantum Roll]] server and inline rolls for all dice functions || ScriptCards includes its own dice roll parser, and '''''does not support''''' inline rolls.<br />
|-<br />
| PowerCards RollIDs (often mistaken for variables) are assigned by analyzing the results of an inline roll, and cannot be referenced in other rolls, so you can't roll a <code>1d4</code> and then roll a <code>1d20</code> and add the <code>1d4</code> result because all of the rolls happen on the chat server before PowerCards gets the macro text. || ScriptCards supports two types of variables: Roll Variables and String Variables. Because ScriptCards uses its own roll parser and is not dependent upon the chat server, rolls and their results can be used in other rolls, math functions, output, etc.<br />
|}<br />
<br />
== Example Scripts ==<br />
<br />
Below are some sample scripts that utilize the various statement types in ScriptCards:<br />
<br />
=== Divine Smite ===<br />
<br />
This script will prompt the user for a spell slot level to expend on a divine smite. It will check the target's npc_type to see if it is an Undead or Fiend, which adds an additional d8 to the smite roll.<br />
<br />
[[File:ScriptCards Divine Smite.png|Divine Smite Script Output]]<br />
<br />
<pre><br />
!scriptcard {{<br />
--#title|Divine Smite<br />
--=DiceCount|?{Spell Slot Level?|1|2|3|4|5|6|7|8|9} + 1<br />
--=IsFiendOrUndead|0<br />
--?"@{target|npc_type}" -inc fiend|>IsBoosted<br />
--?"@{target|npc_type}" -inc undead|>IsBoosted<br />
--=TotalDice|[$DiceCount] + [$IsFiendOrUndead]<br />
--=SmiteRoll|[$TotalDice]d8<br />
--#emoteText|@{selected|token_name} smites @{target|token_name}<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
--+Smite|deals [$SmiteRoll] radiant damage.<br />
--X|<br />
<br />
--:IsBoosted|<br />
--=IsFiendOrUndead|1<br />
--<|<br />
}}<br />
</pre><br />
<br />
==== How It Works ====<br />
<br />
The first line sets the "title" card parameter to "Divine Smite".<br />
<br />
Line 2 Shows a query to the user asking for the spell slot level, adds one and stores the value in the "DiceCount" Roll Variable. The query/dropdown is generated by the chat server prior to the script being executed.<br />
<br />
Line 3 defaults the "IsFiendOrUndead" Roll Variable to 0.<br />
<br />
Lines 4 and 5 compare the target's "npc_type" attribute (passed by the chat server as text) to see if they include either "undead" or "fiend". If true, the IsBoosted subroutine will be called. No parameters are passed to this subroutine.<br />
<br />
Line 6 sets the "TotalDice" variable to the base (DiceCount) number plus the IsFiendOrUndead number, which will be a 0 or a 1.<br />
<br />
Line 7 calculates "SmiteRoll" by rolling a number of d8 equal to the "TotalDice" value.<br />
<br />
Lines 8-10 set the parameters for the emote, which appears above the card content. By setting the sourceToken and the targetToken, their icons will appear in the emote surrounding the text describing the action.<br />
<br />
Line 11 is the only line that actually produces output on the card. It results in "Smite deals # radiant damage".<br />
<br />
Line 12 ends the script execution, preventing the script from continuing and running the subroutines out of context.<br />
<br />
Lines 14-16 are the IsBoosted subroutine, starting with the :IsBoosted label. The IsFiendOrUndead variable is set to 1, and a return from subroutine is executed.<br />
<br />
=== Magic Missile ===<br />
<br />
This script demonstrates using a loop and calling a subroutine to fire a number of missiles determine by the spell slot level used to cast the spell.<br />
<br />
[[File:ScriptCards_MagicMissile_Fixed.png|Magic Missile Script Output]]<br />
<br />
<pre><br />
!scriptcard {{ <br />
--#title|Magic Missile<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
--=MissileCount|?{Spell Slot Level?|1|2|3|4|5|6|7|8|9} + 2<br />
--=DisplayCount|1<br />
--=MissileDamage|0<br />
--#leftsub|Slot level ?{Spell Slot Level?}<br />
--#rightsub|Ranged Attack<br />
--#emoteText|Fred uses a level ?{Spell Slot Level?} spell slot to fire [$MissileCount.Total] missiles of magical force!<br />
--:MissileLoop|<br />
-->FireMissile|<br />
--=DisplayCount|[$DisplayCount] + 1<br />
--?[$DisplayCount] -le [$MissileCount]|MissileLoop<br />
--+Total|Total damage is [$MissileDamage]<br />
--X|<br />
<br />
--:FireMissile|<br />
--=ThisMissile|1d4 + 1<br />
--=MissileDamage|[$MissileDamage] + [$ThisMissile]<br />
--+Missile|[$DisplayCount.Total] Hits for [$ThisMissile] [b]force[/b] damage<br />
--<|<br />
}}<br />
</pre><br />
<br />
==== How It Works ====<br />
<br />
Lines 1-3 set the card title, the source token and the target token. Setting these tokens causes their icons/avatars to appear in the Emote section of the card.<br />
<br />
Line 4 asks the user what spell slot level they wish to use to cast magic missile. The number of missiles fired is equal to 2 plus the spell level, and this is stored in the MissileCount variable.<br />
<br />
Line 5 stores a 1 in the DisplayCount variable. This will be used to control the loop to determine the number of missiles fired and the missile number when displaying damage rolls.<br />
<br />
Line 6 initializes MissileDamage to 0<br />
<br />
Line 7 sets the left subtitle to the text "Slot Level #", where # is the spell slot level being used.<br />
<br />
Line 8 sets the right subtitle to the text "Ranged Attack".<br />
<br />
Line 9 sets the emoteText parameter with a description of the action, including the slot level and number of missiles fired.<br />
<br />
Line 10 is a label for the missile firing loop<br />
<br />
Line 11 Calls the "FireMissile" subroutine<br />
<br />
Line 12 increases the DisplayCount variable by 1<br />
<br />
Line 13 Checks to see if there are still missles to fire (DisplayCount <= MissileCount) and if so branches to MissileLoop<br />
<br />
Line 14 Displays the total damage dealt by the spell.<br />
<br />
Line 15 stops execution of the script to prevent out of context execution of the subroutine.<br />
<br />
Lines 76-21 are the FireMissile subroutine, beginning with the FireMissile label. The 1d4+1 is rolled and assigned to "ThisMissile". The result is added to the existing MissileDamage total, and a line for the current missile is displayed with the missile number and the damage for the missile.<br />
<br />
=== Longsword Attack ===<br />
<br />
This script demonstrates a standard 5E D&D melee weapon attack, including detection of misses, fumbles, hits, and critical hits. If installed, alterbars is used to decrement the target's BAR3 value by the damage dealt.<br />
<br />
[[File:ScriptCards Longsword.png|Longsword Script Output]]<br />
<br />
<pre><br />
!scriptcard {{<br />
--#title|Longsword<br />
--#leftsub|Melee Attack<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
--#emoteText|@{selected|token_name} attacks @{target|token_name}<br />
--=TargetAC|@{target|npc_ac}<br />
--?[$TargetAC.Total] -gt 0|DoneWithAC<br />
--=TargetAC|@{target|ac}<br />
--:DoneWithAC|<br />
--=AttackRoll|1d20 + @{selected|strength_mod} [STR] + @{selected|pb} [PROF]<br />
--+Attack|@{selected|token_name} rolls [$AttackRoll] vs AC [$TargetAC].<br />
--?[$AttackRoll.Base] -eq 20|Crit<br />
--?[$AttackRoll.Base] -eq 1|Fumble<br />
--?[$AttackRoll.Total] -ge [$TargetAC.Total]|Hit<br />
--+Miss|The attack missed.<br />
--^Final|<br />
<br />
--:Fumble|<br />
--+Fumble!|The attack went horribly wrong.<br />
--^Final|<br />
<br />
--:Hit|<br />
--=Damage|1d8 + @{selected|strength_mod} [STR]<br />
--+Hit!|The attack hit @{target|token_name} for [$Damage] slashing damage.<br />
--@alter|_target|@{target|token_id} _bar|3 _amount|-[$Damage]<br />
--^Final|<br />
<br />
--:Crit|<br />
--=Damage|1d8 + @{selected|strength_mod} [STR] + 1d8 [CRIT]<br />
--+Critical Hit!|The attack hit @{target|token_name} for [$Damage] slashing damage.<br />
--@alter|_target|@{target|token_id} _bar|3 _amount|-[$Damage]<br />
<br />
--:Final|<br />
}}<br />
</pre><br />
<br />
==== How it Works ====<br />
<br />
In lines 1-5, we set the title, subtitle, and emote text along with the tokens for the emote area.<br />
<br />
Lines 6-9 allow us to determine the AC of the target. On the 5E Roll20 sheet, NPCs armor class is stored in "npc_ac", while PCs armor class is in "ac". First we grab npc_ac and if it is zero, we check AC.<br />
<br />
Line 10 rolls the attack roll, rolling 1d20 and adding the attacker's strength modifier and proficiency bonus<br />
<br />
Line 11 displays the result of the attack roll on the card<br />
<br />
Lines 12-14 determine what kind of result the attack had. If the .Base value of the roll was 20, we branch to "Crit". If it was 1, we branch to "Fumble". If the .Total value of the roll was greater than or equal to the AC that was determined in Lines 6-9, we branch to Hit.<br />
<br />
Assuming we didn't branc anywhere, the result of the attack was a miss, so we display that on line 15 and then branch to "Final"<br />
<br />
This is followed by three branch segments, :Fumble, :Hit, and :Crit. A fumble displays a text message and branches to :Final.<br />
<br />
On a hit or a crit, we roll Damage (adding additional damage dice on a crit). We display a "Hit!" or "Critical Hit!" message and then make an API call to AlterBars, passing it the token id, bar we want to modify (3 in this case), and the amount we want to modify by the Damage value.<br />
<br />
=== Party Health Status ===<br />
<br />
This example calculates the current Hit Points remaining and HP percentage for each character and creates a color-coded display with the current party status.<br />
<br />
[[File:ScriptCards Party Health.png]]<br />
<br />
<pre><br />
!scriptcard {{<br />
--#title|Party Status<br />
--#titleCardBackground|#33CC33<br />
--#oddrowbackground|#bfee90<br />
--#evenrowbackground|#90eebf<br />
-->HealthCheck|@{Quej Grastra|character_id}<br />
-->HealthCheck|@{Brim Cheuto|character_id}<br />
-->HealthCheck|@{Odug Ututees|character_id}<br />
--X|End of card Execution<br />
<br />
--:HealthCheck|<br />
--=HealthPerc|[*[%1%]:hp] / [*[%1%]:hp^] * 100 \ 1<br />
--=HealthColor|000000<br />
--?[$HealthPerc.Total] -gt 50|HealthSkip<br />
--=HealthColor|FF0000<br />
--:HealthSkip|<br />
--+[*[%1%]:character_name]|has [#[$HealthColor.RollText]][*[%1%]:hp] of [*[%1%]:hp^][/#] HP [R]([$HealthPerc.Total]%)[/R]<br />
--<|End of HealthCheck<br />
}}<br />
</pre><br />
<br />
==== How it Works ====<br />
<br />
Lines 1-4, we set the card title, and set the title background and row background colors to shades of green.<br />
<br />
Lines 5-7 make gosub calls the the "HealthCheck" subroutine, passing in the character ID of each of the named characters (these are the names of the characters in my test game)<br />
<br />
Line 8 terminates the script execution.<br />
<br />
The remaining lines of the script are the HealthCheck subroutine, which works like this:<br />
<br />
Line 10 is the subroutine label (:HealthCheck)<br />
<br />
Line 11 uses the character id passed as a parameter and combines it with character attribute lookup *(...) to retrieve the value of "hp" and "hp<nowiki>^</nowiki>" for the character. The <nowiki>^</nowiki> character is used to specify that we want the MAX value for this attribute for the second call. We divide these two numbers and multiple by 100 to get a percentage. Finally, we use integer division by 1 to round the percentage and drop the decimals. The end result gets stored in the HealthPerc roll variable.<br />
<br />
Line 12 defaults to color of the health text to black<br />
<br />
Line 13 check to see if the health percentage is greater than 50. If so, it branches to HealthSkip, preventing the script from executing line 13.<br />
<br />
Line 14 sets the color of the health text to red<br />
<br />
Line 15 is the label that will be branched to from Line 13 to skip the red coloring<br />
<br />
Line 16 again uses character attribute substitution and the passed parameter value to output a display line containing the character name, the colorized health total, and the percentage value. The percentage is right-justified.<br />
<br />
Line 17 returns from the HealthCheck subroutine.<br />
<br />
=== Expanded Magic Missile Script ===<br />
<br />
This is the expanded and enhanced version of the Magic Missile script covered in {{yt|watch?v=u50xvNzS9Zk | this video}}. It includes visual and audio effects, checking and deducting spell slots, and applying damage using either Token-Mod or Alterbars.<br />
<br />
<pre><br />
!scriptcard {{ <br />
--#title|Magic Missile<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
<br />
-->GetAndCheckSlotInformation|<br />
<br />
--=MissileCount|[$SlotLevel] + 2<br />
--=DisplayCount|1<br />
--=MissileDamage|0<br />
--#leftsub|Slot level [$SlotLevel]<br />
--#rightsub|Ranged Attack<br />
--#emoteText|@{selected|character_name} uses a level [$SlotLevel.Total] spell slot to fire [$MissileCount.Total] missiles of magical force!<br />
<br />
--:MissileLoop|<br />
-->FireMissile|<br />
--=DisplayCount|[$DisplayCount] + 1<br />
--?[$DisplayCount] -le [$MissileCount]|MissileLoop<br />
--+Total|Total damage is [$MissileDamage]<br />
-->DeductSpellSlot|<br />
--#rightsub|Level [$SlotLevel] Left: [$SlotsRemaining] <br />
-->PlayEffects|none;burst-smoke;beam-magic;spell_01<br />
-->ApplyDamageTokenmod|@{target|token_id};3;-[$MissileDamage]<br />
-->ApplyDamageAlterbars|@{target|token_id};3;-[$MissileDamage]<br />
--X|<br />
<br />
--:FireMissile|<br />
--=ThisMissile|1d4 + 1<br />
--=MissileDamage|[$MissileDamage] + [$ThisMissile]<br />
--+Missile|[$DisplayCount.Total] Hits for [$ThisMissile] [b]force[/b] damage<br />
--<|<br />
<br />
--:GetAndCheckSlotInformation|<br />
--=SlotLevel|?{Spell Slot Level?|1|2|3|4|5|6|7|8|9}<br />
--=SlotsTotal|[*S:lvl[$SlotLevel]_slots_total]<br />
--=SlotsExpended|[*S:lvl[$SlotLevel]_slots_expended]<br />
--?[$SlotsExpended.Total] -ge [$SlotsTotal.Total]|NoSlotsLeft<br />
--<|<br />
<br />
--:NoSlotsLeft|<br />
--+|[*S:character_name] has no level [$SlotLevel.Total] spell slots available.<br />
--X|<br />
<br />
--:DeductSpellSlot|<br />
--=SlotsExpended|[$SlotsExpended] + 1<br />
--@setattr|_charid [*S:character_id] _lvl[$SlotLevel]_slots_expended|[$SlotsExpended] _silent<br />
--=SlotsRemaining|[$SlotsTotal] - [$SlotsExpended]<br />
--<|<br />
<br />
--:PlayEffects|Parameters are : source effect; target effect; line effect; sound effect<br />
--vtoken|@{selected|token_id} [%1%]<br />
--vtoken|@{target|token_id} [%2%]<br />
--vbetweentokens|@{selected|token_id} @{target|token_id} [%3%]<br />
--@roll20AM|_audio,play,nomenu|[%4%]<br />
--<|<br />
<br />
--:ApplyDamageTokenmod|Parameters are tokenid;bar#;amount<br />
--@token-mod|_ignore-selected _ids [%1%] _set bar[%2%]_value|[%3%]<br />
--<|<br />
<br />
--:ApplyDamageAlterbars|<br />
--@alter|_target|[%1%] _bar|[%2%] _amount|[%3%]<br />
--<|<br />
}}<br />
</pre><br />
<br />
[[Category:Featured articles]]</div>5004103https://wiki.roll20.net/Script:ScriptCardsScript:ScriptCards2021-09-28T08:02:35Z<p>5004103: /* Echo to Chat (--e) */</p>
<hr />
<div>{{revdate}}<br />
== Introduction ==<br />
'''ScriptCards''' provides a script interpreter that can be used to create powerful macros that display the results of player/NPC actions, or display other information in a pleasing visual format in your game's chat window. The scripting language contains variables (both dice-roll (enhanced numerics) and strings) as well, conditionals, branching, subroutines with parameters, and a set of built-in functions to simplify working with Roll20 information.<br />
{{script overview<br />
|name=ScriptCards<br />
|author={{user profile|2365448|Kurt J.}}<br />
|code=<br />
|version=1.4.0e<br />
|lastmodified=2021-09-24}}<br />
ScriptCards is not game-system specific, and can be used with any system/sheet. Near the end of this Wiki there is a section set aside for libraries that can implement system-specific tasks, with the hope that enthusiasts playing particular systems will create and share utility functions that can be utilized by the wider community.<br />
<br />
The default display style for ScriptCards output is similar to the format used to document player and NPC abilities in Dungeons and Dragons 4th Edition, but does not have any system ties to D&D4E.<br />
<br />
Current OneClick Version : 1.4.0e<br />
<br />
Current Development Version : 1.4.4<br />
<br />
'''''<big>Critically Important: ScriptCards does not use/parse inline rolls. ScriptCards includes its own built-in dice roll parser to allow for the use of variables inside dice rolls. As of version 1.2.3, ScriptCards will now take inline rolls and substitute the total result value in statement strings, meaning that you can utilize inline rolls but ScriptCards will only see the result of the roll, and not parse the roll components itself.</big>'''''<br />
<br />
* {{fpl|9752053/ ScriptCards thread}}<br />
** {{fpl|10000297/ Scritpcard API Working and Sharing}}<br />
* https://github.com/kjaegers/ScriptCards/tree/main/ScriptCards_API - GitHub repository for source before the one-click version is updated.<br />
* {{yt.be|hyR7Jnq4mQM ScriptCards Intro}} 45min, Jan 2021<br />
* {{yt.be|u50xvNzS9Zk ScriptCards Magic Missile Deep Dive}} 39min, Feb 2021<br />
<br />
<br />
__TOC__<br />
=== Is ScriptCards Related to [[PowerCards]]? ===<br />
<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
Check the '''[[#What to Know if you are Coming from PowerCards|What to Know if you are Coming from PowerCards]]'''-section for a comparison table between the two scripts.<br />
<br />
== What is a ScriptCard Script ==<br />
<br />
A ScriptCard Script is text written into the chat window (either typed directly, pasted, or run via a macro) that will produce a card of information in the [[text Chat|chat window]]. A ScriptCard Script is composed of an [[API]] command: <code><nowiki>!scriptcard {{ }}</nowiki></code> enclosing any number of lines that determine the output that will be added to the card. At it simplest, the following macro:<br />
<br />
<pre>!scriptcard {{ }}</pre><br />
<br />
Will produce just a title card that displays “ScriptCards” as the name:<br />
<br />
[[File:Scriptcard blank.png]]<br />
<br />
Of course, this is just the simplest type of macro and isn’t very useful. In order to produce useful output, we need to include lines between the <code><nowiki>{{</nowiki></code> and <code><nowiki>}}</nowiki></code> that direct the API script as to what it should do.<br />
<br />
== Structure of a ScriptCard Line ==<br />
<br />
All ScriptCard lines begin with two dashes, followed by an ''statement identifier character'' that lets ScriptCards what type of line it is. There are several of these, and they are detailed in the next section. After the line type identifier, a Tag name 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.<br />
<br />
Following the Tag is a vertical bar, and then the content of the line itself. Again, each type of line might interpret this content differently.<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Identifier !! Statement Type !! Tag !! Content !! Notes<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--/</nowiki> || Comment || unused || unused || The <code>--/</code> 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--#</nowiki> || 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").<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--+</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--=</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--&</nowiki> || Assign String 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. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--@</nowiki> || 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 (i.e., [[TokenMod|!token-mod]], or [[ChatSetAttr|!setattr]], etc.)<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--:</nowiki> || 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<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--^</nowiki> || Branch To || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--></nowiki> || Call Procedure || 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<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--<</nowiki> || 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.<br />
|- <br />
| style="white-space:nowrap" | <nowiki>--?</nowiki> || Conditional Branch || Condition to be evaluated || True Branch Label<nowiki>|</nowiki>False Branch Label || The condition will be evaluated and execution will jump to one of the two indicated branches (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 included a semicolon separated list of parameters. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--s</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--l</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--v</nowiki> || 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+'''''<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--e</nowiki> || Echo to Chat || Name to send chat command as || Chat message to send || Variable substitution takes place on the tag and content.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--R</nowiki> || Retrieve Repeating Section Row information || "find", "first", or "next" || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--~</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--c</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--i</nowiki> || Information Request || User Prompt;Button Caption || InfoType;VariableName;ParameterText || See full documentation below.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--d</nowiki> || 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. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--%</nowiki> || 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. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--*</nowiki> || 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.<br />
|}<br />
<br />
== ScriptCard Statement Type Details ==<br />
The sections below detail the individual statement types supported by ScriptCards<br />
<br />
=== Comment (--/) ===<br />
<br />
A --/ statement is ignored by the ScriptCards parser. You can use this type of statement to add comments and informational text to your script. <br />
<br />
Example:<br />
<pre><br />
!script {{<br />
--/|Script Name : Fireball<br />
--/|Purpose : Allow the player to cast a fireball and blow stuff up!<br />
.<br />
.<br />
.<br />
}}<br />
</pre><br />
<br />
=== Set Parameter (--#) ===<br />
<br />
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.<br />
<br />
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.<br />
<br />
'''''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.'''''<br />
<br />
Examples:<br />
<pre><br />
--#title|Magic Missile<br />
--#leftsub|Level 1 Spell<br />
--#rightsub|Force Damage<br />
</pre><br />
<br />
The three examples above set the “title”, “leftsub”, and “rightsub” values for the card to the content value for the line. <br />
<br />
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.<br />
Settings Lines do not produce output lines on the card.<br />
<br />
The following settings are available (note that parameter names are ''not'' case sensitive):<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Name !! Effect/Use !! Default Value !! Type<br />
|-<br />
| 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<br />
|-<br />
| allowplaintextinrolls || If set to a non-zero value, plain character text in rolls will be copied to the roll text || 0 || Per-Line<br />
|-<br />
| bodyFontFace || Name of the font used in the card rows || Helvetica || Global<br />
|-<br />
| bodyFontSize || Size of the text in the card rows || 14px || Global<br />
|-<br />
| bodybackgroundimage || Specify an image (content for a CSS background-image tag) for the body area || none || Global<br />
|-<br />
| buttonBackground || Background color for buttons created with [button][/button] || #1C6EA4 || Per-Line<br />
|-<br />
| buttonBorderColor || Border (outline) color for buttons created with [button][/button] || #999999 || Per-Line<br />
|-<br />
| buttonFontFace || Font Family specifier for captions on buttons created with [button][/button] || Tahoma || Per-Line<br />
|-<br />
| buttonFontSize|| Text size for captions on buttons created with [button][/button] || x-small || Per-Line<br />
|-<br />
| buttonTextColor|| Text color of labels on buttons created with [button][/button] || #FFFFFF || Per-Line<br />
|-<br />
| 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<br />
|-<br />
| deferralcharacter || Changes the meta script deferral sequence to the specified value || ^ || Per-Line<br />
|-<br />
| diceFontColor|| Color of the dice created with the [d4] [d6], etc. formatting markers || #1C6EA4 || Per-Line<br />
|-<br />
| dicefontsize || Size of the dice created with the [d4] [d6], etc. formatting markers || 3.0em || Per-Line<br />
|-<br />
| 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<br />
|-<br />
| disablerollprocessing || If set to a non-zero value, --= lines will not process dice rolls strings || 0 || Per-Line<br />
|-<br />
| emoteBackground || Background color of the emote area || #f5f5ba || Global<br />
|-<br />
| emoteFont || Name of the font used in emote area (above the title of the output card) || Georgia || Global<br />
|-<br />
| emoteFontColor || Color of the font in the emote area || None (Empty) || Global<br />
|-<br />
| emoteFontSize || Size of the font used in the emote area || 14px || Global<br />
|-<br />
| emoteFontWeight || Font weight for the font in the emote area || bold|| Global<br />
|-<br />
| emoteState || If set to anything other than "visible", the emote portion of the card will not be displayed || visible || Global<br />
|-<br />
| emoteText || Text to display in the emote portion of the card || None (Empty) || Global<br />
|-<br />
| emotefont || Name of the font used in the emote text area || font-family: Georgia, serif; font-weight: bold; || Global<br />
|-<br />
| evenRowBackground || Hex code for the background color for even rows || #eeeeee || Per-Line<br />
|-<br />
| evenRowFontColor || Hex code for the text color for even rows || #000000 || Per-Line<br />
|-<br />
| evenrowbackgroundimage || Specify an image (content for a CSS background-image tag) for the even card rows || none || Per-Line<br />
|-<br />
| executionlimit || Maximum number of script lines the interpreter will try to execute. This prevents "infinite loop" sandbox crashes || 40000 || Global<br />
|-<br />
| hideCard || If set to any non-default value, the entire card output will be suppressed || 0 || Global<br />
|-<br />
| 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<br />
|-<br />
| 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<br />
|-<br />
| lineheight || Vertical size of each line on the output card || normal || Per-Line<br />
|-<br />
| nominmaxhighlight || If set to anything other than "0", rolls will not display crit/fumble/mixed highlight colors. || 0 || Per-Line<br />
|-<br />
| norollhighlight || If set to anything other than "0", rolls will not be formatted (plain numbers) but will still get a tooltip with details ('''''v1.3.6b+''''') || 0 || Per-Line<br />
|-<br />
| oddRowBackground || Hex code for the background color for even rows || #d0e4f5 || Per-Line <br />
|-<br />
| oddRowFontColor || Hex code for the text color for odd rows || #000000 || Per-Line<br />
|-<br />
| oddrowbackgroundimage || Specify an image (content for a CSS background-image tag) for the odd crd rows || none || Per-Line<br />
|-<br />
| reentrant || Used to name a script for rentrant button use || 0 || Global<br />
|-<br />
| 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)0 || Global<br />
|-<br />
| rollhilightlineheight || Determines the height of the hilight box placed around roll results ('''''1.4.2+''''') || 1.0em || Per-Line<br />
|-<br />
| roundUp || If set to a non-default value, integer division will round up instead of down || 0 || Per-Line<br />
|-<br />
| showfromfornonwhispers || If set to a non-zero value, will include the sender on cards that aren't whispered || 0 || Global<br />
|-<br />
| 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<br />
|-<br />
| subtitleFontColor || Color of the text in the subtitle areas || #FFFFFF || Global<br />
|-<br />
| subtitleFontFace || Name of the font used on the subtitle sections || Tahoma || Global<br />
|-<br />
| subtitleFontSize || Size of the subtitle font || 13px || Global<br />
|-<br />
| subtitleSeperator || The character(s) that will be placed between leftsub and rightsub || <nowiki>&#x2666</nowiki>; || Global<br />
|-<br />
| tableBorderRadius || CSS specifier for how rounded the borders of the output card are. Use "0px;" for square borders || 6px; || Global<br />
|-<br />
| tableShadow || CSS specifier for the drop shadow under the output card || 5px 3px 3px 0px #aaa; || Global<br />
|-<br />
| tablebgcolor || Background color of the whole card. '''''Normally not visible''''' || #EEEEEE || Global<br />
|-<br />
| tableborder || Color of the border that surrounds the whole card || 2px solid #000000; || Global<br />
|-<br />
| 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<br />
|-<br />
| timezone || IANA Specifier for the local time zone, used in system/date functions || merica/New_York || Per-Line<br />
|-<br />
| title || Text displayed in the title area of the card || ScriptCards || Global<br />
|-<br />
| titleCardBackground || A hex color code representing the background color of the title area. || #1c6ea4 || Global<br />
|-<br />
| titleFontColor || Color of the text on the card title || #FFFFFF || Global<br />
|-<br />
| titleFontFace || Name of the font used on the title area || Contrail One || Global<br />
|-<br />
| titleFontLineHeight || Line spacing on the title area || 1.2em || Global<br />
|-<br />
| titleFontSize || Size of the title font || 1.2em || Global<br />
|-<br />
| titlecardbackgroundimage || Specify an image (content for a CSS background-image tag) for the title card area || none || Global<br />
|-<br />
| titlecardbottomborder || Border CSS specifier for the bottom of the title card area || 2px solid #444444; || Global<br />
|-<br />
| titlecardgradient || If set to non-zero value, will place a vertical gradient on the title card area || 0 || Global<br />
|-<br />
| usehollowdice || If set to a non-zero value, the hollow/outline versions of the dice fonts will be used || 0 || Per-Line<br />
|-<br />
| whisper|| Comma separated list of who to whisper the output to. Use "gm" for [[GM|GMs]] and "self" for the sender || none || Global|}<br />
|}<br />
<br />
''Setting Lines do not produce output lines on the card''<br />
<br />
=== Direct Output (--+) ===<br />
<br />
A direct output line display 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.<br />
<br />
Examples of Direct Output lines:<br />
<pre><br />
--+Hello|World<br />
--+Attack|The monster rolls [$Attack] to hit!<br />
--+Damage|@{target|token_name} is hit for [$Damage] [#3333AA][b]frost[/b][/#] damage.<br />
</pre><br />
<br />
Direct Output lines support inline formatting, roll variable replacement, character attribute references, and procedure variables.<br />
<br />
=== GM Output (--*) ===<br />
<br />
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. <br />
<br />
Example:<br />
<pre><br />
--+PlayerLine|This line is shown on the public card<br />
--*GMLine|This line will only be shown to GMs, on a separate card.<br />
</pre><br />
<br />
=== Roll Variable Assignment (--=) ===<br />
<br />
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.<br />
<br />
'''''All components of a roll equation should be separated with spaces.'''''<br />
<br />
Examples:<br />
<pre><br />
--=MissileDamage|1d4 + 1<br />
--=Attack|1d20 + @{selected|strength_mod} [STR] + @{selected|pb} [PROF]<br />
</pre><br />
<br />
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. Text enclosed in square brackets ([]) is considered "flavor text" and will be added to the result text but does not impact the roll result.<br />
<br />
The following dice formats are supported:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Format Pattern !! Example !! Description<br />
|-<br />
| XdY || 3d8 || Simple format. Roll a Y-sided die X times<br />
|-<br />
| XdYkhZ || 2d20kh1 || Roll Y-sided die X times and keep the highest Z number of dice<br />
|-<br />
| XdYklZ || 4d6kl3 || Roll Y-sided die X times and keep the lowest Z number of dice <br />
|-<br />
| XdY>Z || 5d6>3 || Roll Y-sided die X times and count a 1 for each roll greater than Z <br />
|-<br />
| XdY<Z || 5d6<3 || Roll Y-sided die X times and count a 1 for each roll less than Z <br />
|}<br />
<br />
'''''Note: The dice formulae below are supported in the development version of ScriptCards and will be merged with the table above when activated on OneClick'''''<br />
::{| class="wikitable"<br />
|-<br />
! Format Pattern !! Example !! Description<br />
|-<br />
| 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<br />
|-<br />
| 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<br />
|-<br />
| 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)<br />
|-<br />
| 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<br />
|}<br />
<br />
The following operators are supported in a roll equation:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Operator !! Operation<br />
|-<br />
| + || Addition <br />
|-<br />
| - || Subtraction <br />
|-<br />
| * || Multiplication <br />
|-<br />
| / || Division <br />
|-<br />
| \ || Integer Division (Rounds down) <br />
|-<br />
| % || Modulo (Remainder of Divison)<br />
|}<br />
<br />
Roll Variables can be accessed at any time after they have been created by using the [$VariableName] format, with the following optional modifiers:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Modifier !! Meaning<br />
|-<br />
| No modifier || In a Direct Output Line (<nowiki>--+</nowiki>) 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<br />
|-<br />
| .Total || The end result of the roll equation as an unformatted number <br />
|-<br />
| .Base || The cumulative result of any dice rolled in the Roll Text (Numeric modifiers are not included) <br />
|-<br />
| .Ones || The number of dice in the roll that came up as 1s <br />
|-<br />
| .Aces || The number of dice in the roll that came up as the maximum number on the die <br />
|-<br />
| .Odds || The number of dice in the roll that came up with an odd number <br />
|-<br />
| .Evens || The number of dice in the roll that came up with an even number <br />
|-<br />
| .RollText || The raw text of the roll that was use to generate the results <br />
|-<br />
| .Text || A text representation of the results of the roll, including the numbers rolled for each die <br />
|-<br />
| .tableEntryText || The text portion of the result of a table roll<br />
|-<br />
| .tableEntryImgURL || The image source portion of the result of a table roll<br />
|-<br />
| .tableEntryValue || Numeric value of tableEntryText (via parseInt). If a non-numeric value, will be 0<br />
|-<br />
| .Raw || The total numeric result without any formatting, even if placed somewhere formatting would normally be done. <br />
|}<br />
<br />
Examples:<br />
<pre><br />
--+Total Damage|[$MissileDamage.Total] (roll was 1d4+1)<br />
--+Base Damage|[$MissileDamage.Base] (without the +1)<br />
--=Attack|1d20 + @{selected|strength_mod} [STR] + @{selected|pb} [PROF] + [$BlessBonus] [Bless]<br />
</pre><br />
<br />
In this case, 1d4 will be rolled and stored in “BlessBonus”, which can then be used in the Attack line.<br />
<br />
'''''Mathematical Functions in Roll Expressions '''''<br />
<br />
The ScriptCards roll parser works from left to right, always maintaining a current value and applying whatever comes next to the total. The following in-line functions to the roll parser. These are:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Expression !! Meaning<br />
|-<br />
| {ABS} || Absolute Value<br />
|-<br />
| {CEIL} || Ceiling value (round up to the next whole number)<br />
|-<br />
| {FLOOR} || Floor value (round down to the next whole number)<br />
|-<br />
| {ROUND} || Round value (round up if the decimal portion is greater than 0.5, otherwise round down)<br />
|-<br />
| {NEGATE} || Multiply the value by negative one.<br />
|-<br />
| {SQRT} || Take the square root of the running value. ('''''1.4.1+''''')<br />
|-<br />
| {SQUARE} || Square the running value. ('''''1.4.2+''''')<br />
|-<br />
| {CUBEROOT} || Take the cube root of the running value. ('''''1.4.2+''''')<br />
|-<br />
| {CUBE} || Cube the running value. ('''''1.4.2+''''')<br />
|-<br />
| {SIN} || Return the SIN of running value. ('''''1.4.2+''''')<br />
|-<br />
| {COS} || Return the COS of running value. ('''''1.4.2+''''')<br />
|-<br />
| {TAN} || Return the TAN of running value. ('''''1.4.2+''''')<br />
|-<br />
| {ASIN} || Return the ASIN of running value. ('''''1.4.2+''''')<br />
|-<br />
| {ACOS} || Return the ACOS of running value. ('''''1.4.2+''''')<br />
|-<br />
| {ATAN} || Return the ATAN of running value. ('''''1.4.2+''''')<br />
|}<br />
<br />
<br />
'''''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 <nowiki>[[ ]]</nowiki> 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.<br />
<br />
'''''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.<br />
<br />
'''Rolling on Rollable Tables'''<br />
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.<br />
<br />
''Roll Variable Lines do not produce output lines on the card.''<br />
<br />
=== String Variable Assignment (--&) ===<br />
<br />
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:<br />
<br />
<pre><br />
--&MyText|Hello<br />
</pre><br />
<br />
Here, we assign the text "Hello" to the string variable named MyText. You can also append text to a string variable by prefixing the content with a + sign:<br />
<br />
<pre><br />
--&MyText|+ World<br />
</pre><br />
<br />
If run after the statement above, MyText will now contain "Hello World".<br />
<br />
String variables can be referenced using the syntax [&variablename]<br />
<br />
=== Call API (--@) ===<br />
<br />
ScriptCards can use a Call API instruction to execute other API commands. The Tag contains the API 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 API command is executed.<br />
<br />
Examples:<br />
<pre><br />
--@eh|list<br />
--@alter|_target|@{target|token_id} _bar|3 _amount|-[$Damage]<br />
</pre><br />
<br />
In the first example above, the command <code>!eh list</code> will be executed, calling [[EncounterHelper]]. In the second, {{fpl|1216260/ AlterBars}} is called to modify a token's Bar 3 value.<br />
<br />
'''''Note:''''' When ScriptCards (or any API script) runs other API 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).<br />
<br />
See [[API:Script Index]] for more options.<br />
<br />
=== Branch Label (--:) ===<br />
<br />
A branch label defines a line in your code that can be reached by one of the branching instructions (<nowiki>--^</nowiki>, <nowiki>--></nowiki>, or <nowiki>--?</nowiki>). The Tag serves as the label name, and must be unique on the card.<br />
<br />
The vertical bar (|) separator must be present, but the content portion of the line is unused and can be treated as a comment.<br />
<br />
Examples:<br />
<pre><br />
--:MyLoop|<br />
--:CriticalHit|Will jump here if we roll a critical hit!<br />
</pre><br />
<br />
''A Branch Label line does not produce an output line on the card.''<br />
<br />
=== Branch (--^) === <br />
<br />
A Branch line 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.<br />
<br />
Examples:<br />
<pre><br />
--^MyLoop|Jumps to MyLoop<br />
--^SkipCrit|We didn't crit, so skip the Crit code<br />
</pre><br />
<br />
''A Branch line does not produce an output line on the card.''<br />
<br />
=== Call Procedure (-->) ===<br />
<br />
Similar to a branch, a Call Procedure (sometimes knows 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 (<nowiki>--<</nowiki>) 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 (;).<br />
<br />
Examples:<br />
<pre><br />
-->FixFormat|#3333FF;#999999<br />
</pre><br />
<br />
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%].<br />
<br />
=== Return (--<) ===<br />
<br />
A return instruction marks the end of a Gosub procedure. 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.<br />
<br />
Examples:<br />
<pre><br />
--<|<br />
--<|End of MySub<br />
</pre><br />
<br />
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.<br />
<br />
=== Conditional Statement (--?) ===<br />
<br />
A conditional statement contains some equation in the Tag that will be evaluated. '''''If any part of the comparison can/does contain a space, it needs to be surrounded by double quotes'''''<br />
<br />
Based on the true/false result of the evaluation, one of two execution paths will be taken. These execution paths are detailed in the content section of the statement. The "if true" path is specified first (directly after the vertical bar), and the "if false" path is specified after it, also separated by a vertical bar.<br />
<br />
Example:<br />
<pre><br />
--?[$AttackRoll.Total] -ge [$TargetAC]|Hit|Miss<br />
</pre><br />
<br />
'''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.'''<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Branch Format !! Meaning<br />
|-<br />
| Label || If just a label is specified, execution will branch to that label when the comparison is matched.<br />
|-<br />
| >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 <br />
|-<br />
| =VariableName || The roll variable "VariableName" will be assigned the value following a semicolon (ex: --?1 -eq 1|=Roll;1d20)<br />
|-<br />
| &VariableName || The string variable "VariableName" will be assigned the value following a semicolon (ex: --?1 -eq 1|&Result;Hit|&Result;Miss)<br />
|-<br />
| % or %! || The current for...next loop will perform the "next" action (%) or will break out (%!) <br />
|-<br />
| [ || Code block (see below)<br />
|}<br />
<br />
Examples:<br />
<pre><br />
--?[$AttackRoll.Base] -eq 20|CriticalHit<br />
--?[$AttackRoll.Base] -eq 1|>Fumble;@{selected|dexterity_mod}<br />
--?"@{target|npc_type}" -inc "undead"|&MonsterType;Undead|&MonsterType;Not Undead<br />
--?[$Attack.Total] >= [$ArmorClass]|>Hit|>Miss<br />
</pre><br />
<br />
In the first example, if the Base value of AttackRoll is a 20 (natural 20 on the die) execution will branch to the CriticalHit label.<br />
<br />
In the second example, 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%].<br />
<br />
The third example looks for the word "undead" in the npc_type attribute of the targeted character. If it exists in the text, the MonsterType string variable will be set to "Undead", otherwise it will be set to "Not Undead". <br />
<br />
The final example would call 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.<br />
<br />
''Text that does/may contain a space should be enclosed in double quotes.''<br />
<br />
The following comparison operators are available:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Comparator !! Meaning<br />
|-<br />
| -eq || Equal To <br />
|-<br />
| -eqi || Case insensitive Equal To <br />
|-<br />
| -ne || Not Equal To <br />
|-<br />
| -nei || Case insensitive Not Equal To <br />
|-<br />
| -gt || Greater Than <br />
|-<br />
| -ge || Greater Than or Equal To <br />
|-<br />
| -lt || Less Than <br />
|-<br />
| -le || Less Than or Equal To <br />
|-<br />
| -inc || Includes (text strings). <br />
|-<br />
| -ninc || Does Not Include (text strings). <br />
|}<br />
<br />
Multi-part conditionals are supported with -and and -or as separators. For example:<br />
<br />
<pre><br />
--?[$Attack.Total] -ge @{target|npc_ac} -and [$Attack.Base] -ne 20|HitButNotCrit<br />
</pre><br />
<br />
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):<br />
<br />
true AND false OR true<br />
<br />
Will be evaluated as true. The first two (true and false) will be false, but then false OR true will be true.<br />
<br />
Conversely:<br />
<br />
true or false and false<br />
<br />
Will be false, because the first true and false will evaluate to true, and then true and false will be false.<br />
<br />
'''CODE BLOCKS'''<br />
<br />
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.<br />
<br />
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:<br />
<br />
<pre><br />
!script {{<br />
--=Roll|1d2<br />
--+Roll|[$Roll]<br />
--?[$Roll.Total] -eq 2|[<br />
--&Value|Yep!<br />
--+|We are inside the TRUE portion of the block<br />
--]|[<br />
--&Value|Nope<br />
--+|We are inside the FALSE portion of the block<br />
--]|<br />
--+After|the blocks!<br />
--+Value|[&Value]<br />
}}<br />
</pre><br />
<br />
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 --]|. <br />
<br />
At this time, blocks cannot be nested, and can only be created as part of a conditional (--[ is not a valid statement type)<br />
<br />
''A conditional statement does not produce a line of output on the card.''<br />
<br />
=== Case Statement (--c) ===<br />
<br />
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 (:). Each match condition includes a branch label that will be used if the test value matches the item. 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:<br />
<br />
<pre><br />
!script {{<br />
--#title|Case Statement Testing<br />
--=Roll|1d4<br />
--C[$Roll.Total]|1:>One;[$Roll]|2:>Two;[$Roll]|3:>Three;[$Roll]|4:>Four;[$Roll]<br />
--X|<br />
<br />
--:One| --+Value|was One ([%1%]) --<|<br />
--:Two| --+Value|was Two ([%1%]) --<|<br />
--:Three| --+Value|was Three ([%1%]) --<|<br />
--:Four| --+Value|was Four ([%1%]) --<|<br />
}}<br />
</pre><br />
<br />
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 variable as a parameter.<br />
<br />
=== Save and Load (--s and --l) ===<br />
<br />
This statement pair is used to either store (--s) or load (--l) data from persistent storage. Items stored in persistent storage remain between card rolls and between Roll20 sessions. There are two types of data that can be stored: settings and roll variables. <br />
<br />
Examples:<br />
<br />
<pre><br />
--Ssettings|GreenStyle<br />
--Srollvariables|FirstCardVars<br />
</pre><br />
<br />
In this case, the tag for the statement determines what type of item is being saved (settings or rollvariables). When saving settings, all non-default settings are written to the named setting storage value. When Roll Variables are saved, all variables that currently exist will be saved to the named storage value.<br />
<br />
Loading stored items simply requires the same command with the --l statement type:<br />
<br />
<pre><br />
--Lsettings|GreenStyle<br />
--Lrollvariables|FirstCardVars<br />
</pre><br />
<br />
When loading settings, all stored settings will be applied to the current card settings. You can override settings by changing them after the load.<br />
<br />
When loading roll variables, the saved variables will be added to (or overwrite if they have the same name) any variables on the current card. This means it is safe to create roll variables before the load statement.<br />
<br />
'''Practical Uses'''<br />
The major intended use of persistent storage is for storing card formats for use in later scripts. For example, the following script:<br />
<br />
<pre><br />
!scriptcard {{<br />
--#titlecardbackground|#22CC22<br />
--#oddrowbackground|#cceecc<br />
--#evenrowbackground|#99ee99<br />
--Ssettings|@{selected|token_name}<br />
}}<br />
</pre><br />
<br />
Would save the titlecardbackground, oddrowbackground, and evenrowbackground settings to a saved list named after the selected token's name. When creating cards for that token to run later, you could include the line:<br />
<br />
<pre><br />
--Lsettings|@{selected|token_name}<br />
</pre><br />
<br />
To load all of the settings at once. By creating these setting sets for each character, you can specify a different color scheme for each character that can then be used in cards with a single formatting line.<br />
<br />
There is a supplemental ! command added to support saved settings:<br />
<br />
<pre><br />
!sc-liststoredsettings<br />
</pre><br />
<br />
Will produce a list of all stored setting names, with buttons to list the setting values stored in each group and a button to delete groups as needed.<br />
<br />
=== Visual Effects (--v) ===<br />
<br />
The --v statement can be used to create visual effects on the tabletop. The tag portion of the statement can be either "token" or "betweentokens". The content portion of the statement contains the required parameters for the effect generation, separated by spaces. If the effect is "none", no effect will be played. If any other value that doesn't match a Roll20 effect name will result in a burst-fire effect.<br />
<br />
For "token" effects, the parameters are the token id for the token the effect happens on, followed by the effect specifier.<br />
<br />
Example:<br />
<pre><br />
--vtoken|@{selected|token_id} burst-fire<br />
</pre><br />
<br />
For "betweentoken" effects, the parameters are the source token id, the target token id, and the effect specifier.<br />
<br />
Example:<br />
<pre><br />
--vbetweentokens|@{selected|token_id} @{target|token_id} beam-magic<br />
</pre><br />
<br />
'''''Version 1.2.8+'''''<br />
<br />
An additional effect specifier, "point" is available in 1.2.8+. This specifier allows you to create a visual effect at a designated X/Y pixel coordinate. Future updates will add custom-vfx support to this option. The parameters are the X and Y coordinates and the effect descriptor. As of version 1.2.9, you can also use custom effect specifiers with Point effects:<br />
<br />
<pre><br />
--vpoint|150 200 burst-fire<br />
</pre><br />
<br />
=== Echo to Chat (--e) ===<br />
<br />
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.<br />
<br />
Example:<br />
<pre><br />
--eThe Ghost|/em hovers around @{selected|character_name}... BOO!<br />
</pre><br />
<br />
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).<br />
<br />
'''''Whispering'''''<br />
<br />
You can use the echo statement to send a whisper, but there's a trick to it. If you execute this code here:<br />
<br />
<pre><br />
--eThe Ghost|/w ExamplePlayerName Boo.<br />
</pre><br />
<br />
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.<br />
<br />
So, in conclusion, it's best to use something like this when you're sending a whisper:<br />
<br />
<pre><br />
!script {{<br />
--#hidecard|1<br />
--&sender|The Ghost<br />
--&receiver|ExamplePlayerName<br />
--&message|Boo.<br />
--e[&sender]|/w [&receiver] [&message]<br />
--eScriptCards|/w gm **Whispered from [&sender] to [&receiver]:** [&message] <br />
}}<br />
</pre><br />
<br />
This will ensure that you see the message in your chat feed as well.<br />
<br />
=== Repeating Section Access (--R) ===<br />
<br />
ScriptCards (as of v0.0.13) supports accessing repeating section rows on a character sheet with the --R statement type. <br />
<br />
There are three basic commands you can use with --R, and they are specified by the tag used:<br />
<br />
<pre><br />
--Rfind|characterid;EntryName;SectionPrefix;SearchField<br />
</pre><br />
<br />
This is the most direct way to access a repeating section row. Supplying the character ID, followed by what you are looking for (Greatsword, for example), followed by the character sheet's section prefix (repeating_attack), followed by the field to check what you are searching for (atkname) will load the matching section (if found) into the script parsers memory. For example:<br />
<br />
<pre><br />
--Rfind|@{selected|character_id};Greatsword;repeating_attack;atkname<br />
</pre><br />
<br />
Will look at the character's "repeating_attack" section for an entry with an atkname value equal to "Greatsword". Similarly:<br />
<br />
<pre><br />
--Rfind|@{selected|character_id};Bite;repeating_npcaction;name<br />
</pre><br />
<br />
Will look for a "Bite" action on an NPC's action list.<br />
<br />
<pre><br />
--Rfirst|characterid;section prefix<br />
</pre><br />
<br />
This form of the --R command will look at all of the entries in the specified repeating section and load the first one into memory:<br />
<br />
<pre><br />
--Rfirst|@{selected|character_id};repeating_attack<br />
</pre><br />
<br />
Would load the character's first "repeating_attack" row into memory.<br />
<br />
<pre><br />
--Rnext|<br />
</pre><br />
<br />
No parameters are required for --Rnext, which loads the next entry in the list that was obtained with "first" into memory.<br />
<br />
However a row is obtained, it will be parsed to replace any attribute references (ie, @{level}) with the corresponding character attribute.<br />
<br />
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".<br />
<br />
You can reference repeating attribute data using the syntax [*R:attributename] syntax (similar to referencing standard character attributes).<br />
<br />
Here are some examples:<br />
<br />
Display the details of the "Greatsword" PC attack:<br />
<br />
<pre><br />
!script {{<br />
--Rfind|@{selected|character_id};Greatsword;repeating_attack;atkname<br />
--+Attack Name|[*R:atkname]<br />
--+Base Damage|[*R:dmgbase]<br />
}}<br />
</pre><br />
<br />
[[File:Scriptcards repeating greatsword.png|Repeating Greatsword Attack]]<br />
<br />
List all of the actions an NPC can take (just actions, not legendary, etc.)<br />
<br />
<pre><br />
!script {{<br />
--#title|NPC Actions<br />
--#leftsub|@{selected|token_name}<br />
--Rfirst|@{selected|character_id};repeating_npcaction<br />
--:DisplayLoop|<br />
--?"[*R:name]" -eq NoRepeatingAttributeLoaded|Done<br />
--+Action:|[*R:name] [*R:attack_damage] [*R:attack_damagetype]<br />
--?"[*R:attack_damage2]" -eq ""|NoSecondaryDamage<br />
--+ |[*R:attack_damage2] [*R:attack_damagetype2]<br />
--:NoSecondaryDamage|<br />
--Rnext|<br />
-->DisplayLoop| <br />
--:Done|<br />
}}<br />
</pre><br />
<br />
[[File:Scriptcards repeating npcactions.png]]<br />
<br />
In the script above, we get the "first" repeating_npcaction and display information about it. We then execute "next" and repeat until we run into "NoRepeatingAttributeLoaded".<br />
<br />
'''''Special debugging command: dump'''''<br />
<pre><br />
--Rdump|<br />
</pre><br />
<br />
The "dump" command will list all of the attributes ScriptCards knows about for the currently loaded repeating row to the API Console Log.<br />
<br />
=== Assign Variable to Built-In Function (--~) ===<br />
<br />
ScriptCards has the ability to run a function built into the API script and return the results to a variable. Some functions return roll variables, while others return strings. See the function table below for details. The format is:<br />
<br />
--~VariableName|function;param1;param2;param3;...<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Function Name !! Parameters !! Description<br />
|-<br />
| distance || token_A_ID;token_B_ID || Calculate the Chebyshev distance in grid units between two tokens. This is the measurement scheme D&D 4E/5E use for diagonal distance measurement<br />
|-<br />
| euclideandistance || token_A_ID;token_B_ID || Calculate the Euclidean distance between two tokens. This is essentially the Pythagorean theorem in action. Returns the result in grid units.<br />
|-<br />
| euclideanpixel || token_A_ID;token_B_ID || Calculate the Euclidean distance between two tokens and returns the result is pixels instead of grid units. <br />
|-<br />
| euclideanlong || token_A_ID;token_B_ID || 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 is calculated instead of before. More accurate over long distances. <br />
|-<br />
| manhattandistance || token_A_ID;token_B_ID || Also called "taxicabdistance" (which is an acceptable function name), this measures to how-many-over, how-many-up/down distance, disallowing diagonal movement.<br />
|-<br />
| getselected || none || 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 the first selected token, VariableName2 the second, etc.<br />
|}<br />
<br />
'''''Functions with Sub Functions'''''<br />
<br />
Most ScriptCards functions are grouped into set as sub functions. The table below lists the major functions and their sub functions.<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Function Name !! Sub Function !! Parameters !! Return Type !! Description<br />
|-<br />
| array || define || arrayname;value1;value2;... || none || Creates an array called "arrayname" and adds value1, value2, etc. to the array<br />
|-<br />
| array || sort || arrayname || none || Sorts the specified array in place in ascending order<br />
|-<br />
| array || add || arrayname;value1;value2;... || none || Adds value1, value2, ... to the existing array "arrayname"<br />
|-<br />
| array || remove || arrayname;value1;value2;... || none || Removes value1, value2, ... from the existing array "arrayname". Resets the array index to 0.<br />
|-<br />
| array || replace || arrayname;currentvalue;newvalue || none || Replaces all occurrences of "currentvalue" in "arayname" with "newvalue"<br />
|-<br />
| array || setatindex || arrayname;index;newvalue || none || Replaces the array item at index "index" with "newvalue"<br />
|-<br />
| array || getindex || arrayname || stringVariable || Retrieves the current index in "arrayname" and stores it in the supplied string variable<br />
|-<br />
| array || setindex || arrayname;newindex || none || Sets the current index in array "arrayname" to "newindex"<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| array || removeat || arrayname;indexposition || none || Removes the item at index "indexposition" from "arrayname". Resets the current array index to 0.<br />
|-<br />
| array || indexof || arrayname;searchvalue || stringVariable || Searches the array "arrayname" for and item with the value of "searchvalue" and, if found, returns the index of the first matching value or "ArrayError" if not found<br />
|-<br />
| array || getlength || arrayname || stringVariable || Returns the number of items in array "arrayname"<br />
|-<br />
| array || pagetokens || arrayname;tokenid;(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. 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.)<br />
|-<br />
| 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.<br />
|-<br />
| array || stringify || arrayname || stringVariable || Returns all of the items in "arrayname" as a string separated by semicolons (;)<br />
|-<br />
| array || fromstring || arrayname || delimiter;string || Creates an array from "string", splitting "string" on "delimiter" to separate the items<br />
|-<br />
| array || statusmarkers|| arrayname;tokenid || none|| Creates an array (arrayname) of the active statusmarkers (sometimes called Token Markers) for the specified tokenid<br />
|-<br />
| math || angle || math;angle;tokenid;tokenid|| rollVariable || Calculates the angle between two tokens and returns the value in degrees<br />
|-<br />
| math || ceil || math;ceil;value || rollVariable || Rounds '''value''' up to the next integer, dropping any decimal portion of the number<br />
|-<br />
| math || clamp || math;clamp;value;lowerBound;upperBound || rollVariable || Returns '''value''', but restricted to the range of '''loweBound''' and '''upperBound'''.<br />
|-<br />
| math || floor || math;floor;value || rollVariable || Rounds '''value''' down, dropping any decimal portion of the number<br />
|-<br />
| math || max || math;max;valueA;valueB || rollVariable || Returns the larger of '''valueA''' vs '''valueB'''<br />
|-<br />
| math || min || math;min;valueA;valueB || rollVariable || Returns the smaller of '''valueA''' vs '''valueB'''<br />
|-<br />
| math || round || math;round;value || rollVariable || Rounds '''value''' to the nearest integer<br />
|-<br />
| string || length || string;length;stringValue || rollVariable || Returns the length of '''stringValue''' in characters<br />
|-<br />
| string || before || string;before;searchText;stringValue || stringVariable || Searches '''stringValue''' for '''searchText''' and returns the portion of '''stringValue''' prior to that text<br />
|-<br />
| string || after || string;after;searchText;stringValue || stringVariable || Searches '''stringValue''' for '''searchText''' and returns the portion of '''stringValue''' after that text<br />
|-<br />
| string || left || string;left;count;stringValue || stringVariable || Returns the leftmost '''count''' characters of '''stringValue'''<br />
|-<br />
| string || right || string;right;count;stringValue || stringVariable || Returns the rightmost '''count''' characters of '''stringValue'''<br />
|-<br />
| string || replace || string;replace;searchText;replaceText;stringValue || stringVariable || Replaces '''searchText''' in '''stringValue''' with '''replaceText''' and returns the resulting string<br />
|-<br />
| string || replaceall || string;replace;searchText;replaceText;stringValue || stringVariable || Replaces all intances of '''searchText''' in '''stringValue''' with '''replaceText''' and returns the resulting string '''''Requires 1.2.9+'''''<br />
|-<br />
| string || trim || string;trim;stringValue || stringVariable || Removes leading and trailing spaces from stringValue and returns the result. <br />
|-<br />
| string || substring || string;substring;start;count;stringValue || stringVariable || Returns '''count''' characters starting at '''start''' from '''stringValue'''<br />
|-<br />
| 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.<br />
|-<br />
| string || tolowercase || string;tolowercase;stringValue || stringVariable || Converts the passed string to lower case and assigns to the passed variable name. <br />
|-<br />
| string || touppercase || string || stringVariable || Converts the passed string to upper case and assigns to the passed variable name. <br />
|-<br />
| 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. <br />
|-<br />
| 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.<br />
|-<br />
| 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'''.<br />
|-<br />
| turnorder || clear || none || none || Clears all entries from the {{Turn Tracker}}/Initiative<br />
|-<br />
| turnorder || addtoken || tokenid;trackervalue || none || Adds the token represented by "tokenid" to the initiative tracker with an initiavie value of "trackervalue"<br />
|-<br />
| turnorder || replacetoken || tokenid;trackervalue || none || Replaces the token represented by "tokenid" in the initiative tracker with an initiavie value of "trackervalue". Will add the token if it doesn't exist in the tracker.<br />
|-<br />
| turnorder || removetoken || tokenid || none || Removes the token represented by "tokenid" from the initiative tracker if it exists<br />
|-<br />
| turnorder || addcustom || textlabel;trackervalue || none || Add a custom text entry to the {{Turn Tracker}}/Initiative named "textlabel" with an initiative value of "trackervalue"<br />
|-<br />
| system || date || getdatetime || stringVariable || Returns the date time in the active timezone (see settings) <br />
|-<br />
| system || date || getdate || stringVariable || Returns the date in the active timezone (see settings) <br />
|-<br />
| system || date || gettime || stringVariable || Returns the time in the active timezone (see settings)<br />
|-<br />
| system || dumpvariables || "rolls", "string", or "array" || none || Dumps all of the defined variables of the indicated type to the console log<br />
|-<br />
| system || findability || system;findability;charactername;abilityname || stringVariable || Returns the object ID of the ability on the indicated character or "AbilityNotFound"<br />
|-<br />
|}<br />
<br />
Examples:<br />
<br />
<pre><br />
--~HowFarAway|distance;@{selected|token_id};@{target|token_id}<br />
</pre><br />
<br />
Returns the distance (Chebyshev) between the selected and target tokens and stores it in "HowFarAway".<br />
<br />
<pre><br />
--SelectedDudes|getselected<br />
</pre><br />
<br />
If 5 tokens were selected, 6 variables would be created: SelectedDudesCount (with a value of 5), SelectedDudes1, SelectedDudes2, SelectedDudes3, SelectedDudes4, SelectedDudes5.<br />
<br />
=== Information Request (--i) ===<br />
<br />
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.<br />
<br />
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.<br />
<br />
After the user has clicked the button and responded to the requests, ScriptCards will resume processing the script from where it left off.<br />
<br />
Here is an example “i” line:<br />
<br />
<pre><br />
--IScriptCards needs additional information to continue;Click to select a target and provide information|t;MyNewTarget;Missile1Target||q;MyNameIs;What is your name?<br />
</pre><br />
<br />
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.<br />
<br />
Supported information request types are “t” for target token, and “q” for query.<br />
<br />
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).<br />
<br />
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:<br />
<br />
<pre><br />
q;UserName;What is your name?|Fred|Bob|Sally|Nancy<br />
</pre><br />
<br />
Would have a dropdown menu with four choices.<br />
<br />
== Inline Formatting ==<br />
<br />
Inline formatting is processed on Direct Output lines only (--+ lines) and the following inline format markup is available:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Formatting Tags !! Description<br />
|-<br />
| [b]..[/b] || Bold the text between the markers <br />
|-<br />
| [i]..[/i] || Italicize the text between the markers <br />
|-<br />
| [u]..[/u] || Underline the text between the markers <br />
|-<br />
| [s]..[/s] || Strike-Thru the text between the markers <br />
|-<br />
| [c]..[/c] || Center alignment <br />
|-<br />
| [l]..[/l] || Left alignment <br />
|-<br />
| [r]..[/r] || Right alignment <br />
|-<br />
| [j]..[/j] || Full justification alignment <br />
|-<br />
| [#xxx]..[/#] or [#xxxxxx]..[/#] || Use a 3 or 6 digit hex code to colorize the text between the markers <br />
|-<br />
| [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, <code>[img width=128 height=128]</code> )<br />
|-<br />
| [button]caption::action[/button] || Create a button with the label "caption" that performs the action defined by "action". <br />
|-<br />
| [t] || Converted to HTML table tag. Text after the "t" will be included inside the tag (width, border, etc)<br />
|-<br />
| [/t] || Converted to HTML close table tag.<br />
|-<br />
| [tr] || Converted to HTML table row tag. Text after the "tr" will be included inside the tag<br />
|-<br />
| [/tr] || Converted to HTML close table row tag.<br />
|-<br />
| [td] || Converted to HTML table cell tag. Text after the "tr" will be included inside the tag<br />
|-<br />
| [/td] || Converted to HTML close table cell tag.<br />
|}<br />
<br />
== Variables ==<br />
<br />
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. While it is possible to assign both a string and a roll variable the same name, doing so will likely result in confusion when looking at the script later, so it is not recommended.<br />
<br />
String Variables are assigned with the --& statement and are referenced using [&variableName] notation.<br />
<br />
Roll Variables are assigned with the --= statement, and the assignment value is always processed by the ScriptCards Roll Processor (resolves dice rolls, etc.)<br />
<br />
There are a handful of variables assigned automatically when a ScriptCard is executed. These are all string variables, and are:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Variable !! Value<br />
|-<br />
| SendingPlayerID || Contains the object ID of the player that sent the macro<br />
|-<br />
| SendingPlayerName || Contains the display name of the player<br />
|-<br />
| SendingPlayerColor || Contains the color code associated with the player<br />
|-<br />
| SendingPlayerSpeakingAs || The contents of the "Speaking As" dropdown window<br />
|-<br />
| SendingPlayerIsGM || Contains 1 if the player is a GM, and 0 if the player is NOT a GM<br />
|}<br />
<br />
== Arrays ==<br />
<br />
Arrays are a special type of variable, and are managed by the function (<nowiki>--~</nowiki> command). All of the array function commands follow the same pattern:<br />
<br />
<pre>--~variableName|array;subcommand;arrayname;param1;param2;param3;...</pre><br />
<br />
Not all array commands return anything to "variableName". The function table above will specify the return type of the command if any.<br />
<br />
There are a couple of different ways to create an array:<br />
<br />
The '''define''' array subcommand creates (or recreates) an array and assigns it values - one for each included parameter after the array name. For example:<br />
<br />
<pre>--~|array;define;Fruits;mango;peach;strawberry;apricot;banana;apple</pre><br />
<br />
will create an array called '''Fruits''' with 6 elements in the order listed in the command (mango, peach, etc.)<br />
<br />
You can also use two other subcommands to create arrays based on tokens:<br />
<br />
<pre>--~Count|array;pagetokens;Everybondy;@{selected|token_id}</pre><br />
<br />
and<br />
<br />
<pre>--~Count|array;selectedtokens;Selected</pre><br />
<br />
In both cases, arrays of tokens will be created, and a string variable called "Count" will be set to the number of tokens in the array. The '''pagetokens''' command returns (by default) all of the tokens on the page that contains the token passed as the parameter after the array name. You can filter the tokens that "pagetokens" includes in the array by appending an optional parameter describing the type of token you are looking for:<br />
<br />
<pre>--~Count|array;pagetokens;Everybondy;@{selected|token_id};npc</pre><br />
<br />
Will return only tokens on the page that represent characters that do not have a ''controlledby'' parameter set. The available options are "all" (default), "char", "graphic", "pc", and "npc".<br />
<br />
The '''selectedtokens''' command returns an array with all of the tokens that were selected when the script was called.<br />
<br />
You can also use an arbitrary string to create an array, specifying a delimiter with the '''fromstring''' command:<br />
<br />
<pre><br />
--&names|Fred<br />
--&names|+,Sally<br />
--&names|+,Ted<br />
--&names|+,Joyce<br />
--~|array;fromstring;,;[&names]<br />
</pre><br />
<br />
The above example builds a comma-separated string and then uses "fromstring" to create an array with 4 elements from it, specifying the comma as the delimiter.<br />
<br />
Finally, you can use the '''statusmarkers''' command to create an array with one entry for each active status marker on a specified token:<br />
<br />
<pre>--~|array;statusmarkers;Conditions;@{selected|token_id}</pre><br />
<br />
will create an array with one entry for each status active on the selected token. The array elements will be the internal name of the status (if you are using custom status marker packs, the names will be specified in the marker pack).<br />
<br />
'''Traversing Arrays'''<br />
<br />
Each array keeps track of an internal index position (starting at 0). Several commands let you manage this index:<br />
<br />
*'''getindex''' returns the current index value<br />
*'''setindex''' sets the index to the specified location in the array<br />
*'''getlength''' returns the number of elements in the array<br />
*'''indexof''' returns the index location of the specified element<br />
<br />
Other commands let you retrieve values from the array:<br />
<br />
*'''getfirst''' sets the index to 0 and returns the value at that position<br />
*'''getnext''' advances the index by 1 and returns the new current value<br />
*'''getprevious''' reduces the index by 1 and returns the new current value<br />
*'''getlast''' sets the index to the last elements in the array and returns the new current value<br />
<br />
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.<br />
<br />
'''Manipulating Array Elements'''<br />
<br />
Several array commands deal with inserting, removing, and modifying elements:<br />
<br />
*'''add''' works just like define, except that it takes an existing array and adds elements to it based on the passed parameters<br />
*'''remove''' looks for items matching each passed parameter and removes them from the indicated array if they exist<br />
*'''removeat''' allows you to specify an index location in the array and remove the element at that position<br />
*'''replace''' searches an array for a value and replaces all occurrences of it with a new value (if found)<br />
*'''sort''' sorts the elements in the array in ascending order<br />
*'''strinfigy''' returns a string variable that includes each array element separated by semicolons (;) <br />
<br />
'''Referencing Array Elements'''<br />
<br />
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.<br />
<br />
<pre><br />
!script {{<br />
--~dummy|array;pagetokens;myarray;@{selected|token_id}<br />
--~count|array;getcount;myarray<br />
--+Total:|There are [&count] graphical objects on the page<br />
--~testvar|array;getfirst;myarray<br />
--:loop|<br />
--+Value|[*[&testvar]:character_name]<br />
--~testvar|array;getnext;myarray<br />
--?[&testvar] -ne ArrayError|loop<br />
--+Loop1|Is Done!<br />
}}<br />
</pre><br />
<br />
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:<br />
<br />
<pre><br />
!script {{<br />
--~dummy|array;pagetokens;myarray;@{selected|token_id}<br />
--~count|array;getcount;myarray<br />
--+Total:|There are [&count] graphical objects on the page<br />
--%loopCounter|1;[&count]<br />
--+Value|[*[@myarray([&loopCounter])]:character_name]<br />
--%|<br />
--+Loop|Is Done!<br />
}}<br />
</pre><br />
<br />
This line : <nowiki>--+Value|[*[@myarray([&loopCounter])]:character_name]</nowiki> uses [@arrayName(index)] format (inside a [*characterid:attribute] syntax) to perform the same task as running through the loop with the index.<br />
<br />
(Note: Additional examples are on the way...)<br />
<br />
== For...Next Loops ==<br />
<br />
For...Next loops in ScriptCards are supported with the with the --% statement type. A loop is defined by starting off with:<br />
<br />
<pre><br />
--%LoopCounter|<start>;<end>;[step]<br />
</pre><br />
<br />
The start and end values are required, while the step parameter is optional. If the step is omitted, it will be assumed to be 1. A string variable named after the line tag ("LoopCounter" in the case above) will be created and will hold the current iteration value for the loop. Here is a real example:<br />
<br />
<pre><br />
--%LoopCounter|1;10;1<br />
</pre><br />
<br />
This will begin a loop identified by "LoopCounter" that will start at 1, increasing by 1 each iteration (the step) until it has completed 10 executions.<br />
<br />
The "next" statement is simply <code>--%|</code>, with no tag or parameters. This indicates to ScriptCards that it should increment the counter and go back to the beginning of the loop. Extending the example above:<br />
<br />
<pre><br />
!script {{<br />
--%LoopCounter|1;10;1<br />
--=Roll|1d20<br />
--+Loop|Counter is [&LoopCounter], roll was [$Roll]<br />
--%|<br />
}}<br />
</pre><br />
<br />
The <code>--%!|</code> sequence will break out of the loop, no matter how many iterations are remaining.<br />
<br />
The % and %! character sequences can also be used as part of a 1.2.1+ non-branching conditional to continue or break the loop:<br />
<br />
<pre><br />
--?"X[&RollInto]X" -eq "XX"|%<br />
</pre><br />
<br />
In this example, if the string variable RollInfo is empty, the loop will return to the top and continue with the next iteration, while:<br />
<br />
<pre><br />
--?"X[&RollInto]X" -eq "XX"|%!<br />
</pre><br />
<br />
Would cause the whole loop to end if the condition were true.<br />
<br />
== Referencing ==<br />
<br />
=== Roll Variables===<br />
<br />
Roll Variables can be referenced from the content portion of any line type, and from the tag portion of conditional statements. The referenced value is replaced when the line is executed.<br />
<br />
There are several modifiers that can be used to reference parts of a roll:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Modifier !! Meaning<br />
|-<br />
| No modifier || In a Direct Output Line (<nowiki>--+</nowiki>), GM Output Line (<nowiki>--*</nowiki>), or String Assignement (<nowiki>--&</nowiki>), 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<br />
|-<br />
| .Total || The end result of the roll equation. Formatting rules for "No Modifier" apply based on line type. <br />
|-<br />
| .Raw || The total value of the roll variable without any formatting, no matter what kind of line the reference is used in.<br />
|-<br />
| .Base || The cumulative result of any dice rolled in the Roll Text (Numeric modifiers are not included) <br />
|-<br />
| .Ones || The number of dice in the roll that came up as 1s <br />
|-<br />
| .Aces || The number of dice in the roll that came up as the maximum number on the die <br />
|-<br />
| .Odds || The number of dice in the roll that came up with an odd number <br />
|-<br />
| .Evens || The number of dice in the roll that came up with an even number <br />
|-<br />
| .RollText || The raw text of the roll that was use to generate the results <br />
|-<br />
| .Text || A text representation of the results of the roll, including the numbers rolled for each die <br />
|-<br />
| .tableEntryText || The text portion of the result of a table roll<br />
|-<br />
| .tableEntryImgURL || The image source portion of the result of a table roll<br />
|-<br />
| .tableEntryValue || If the tableEntryText is purely numeric, will contain the numeric value<br />
|}<br />
<br />
=== String Variables ===<br />
<br />
To reference a string variable, use the notation [&variablename]. String variables can be referenced in direct output, roll variable assignment, and string variable assignment statements.<br />
<br />
=== Character/Token Attributes ===<br />
<br />
A character or token attribute can be referenced from content portion of any type of line and is substituted when the line is executed. The general format for referencing a character attribute is [*ID:attribute]. ID can be a token ID or a character ID (these start with a dash). Additionally if you have specified a sourceToken or targetToken, you can substitute "S" or "T" for the ID (for example [*S:npc_type] will retrieve the npc_type attribute from the source token.<br />
<br />
By default, all attribute references will be pulled from the '''''character''''' object that the ID represents (either directly or by being a Token ID that represents a character).<br />
<br />
Keep in mind, that if you want to access the "max" of an attribute (for example, the max hit points), then you cannot trust the name that your roll20 character sheet shows you when you hover your mouse over the max hit points. For example, this reference will not work: [*S:hp_max]. Instead, you need to use this reference: [*S:hp^].<br />
<br />
If your ID refers to a token, token attributes can be accessed by preceding the attribute name with "t-", for example [*S:t-aura1_radius]. Supported token attributes are:<br />
<br />
{|<br />
| t-name || t-id || t-statusmarkers || t-bar1_value<br />
|-<br />
| t-bar1_max || t-bar2_value || t-bar2_max || t-bar3_value<br />
|-<br />
| t-bar3_max || t-top || t-left || t-width<br />
|-<br />
| t-height || t-rotation || t-layer || t-aura1_radius<br />
|-<br />
| t-aura1_color || t-aura2_radius || t-aura2_color || t-aura1_square<br />
|-<br />
| t-aura2_square || t-tint_color || t-light_radius || t-light_dimradius<br />
|-<br />
| t-light_angle || t-light_losangle || t-light_multiplier || t-light_otherplayers<br />
|-<br />
| t-light_hassight || t-flipv || t-fliph || t-controlledby<br />
|-<br />
| t-_cardid || t-_pageid || t-imgsrc || t-bar1_link<br />
|-<br />
| t-bar2_link || t-bar3_link || t-represents || t-layer<br />
|-<br />
| t-isdrawing || t-name || t-gmnotes || t-showname<br />
|-<br />
| t-showplayers_name || t-showplayers_bar1 || t-showplayers_bar2 || t-showplayers_bar3<br />
|-<br />
| t-showplayers_aura1 || t-showplayers_aura2 || t-playersedit_name || t-playersedit_bar1<br />
|-<br />
| t-playersedit_bar2 || t-playersedit_bar3 || t-playersedit_aura1 || t-playersedit_aura2<br />
|-<br />
| t-lastmove || t-adv_fow_view_distance || t-has_bright_light_vision || t-has_night_vision<br />
|-<br />
| t-night_vision_distance || t-emits_bright_light || t-bright_light_distance || t-emits_low_light<br />
|-<br />
| t-low_light_distance || t-has_limit_field_of_vision || t-limit_field_of_vision_center || t-limit_field_of_vision_total<br />
|-<br />
| t-has_limit_field_of_night_vision || t-limit_field_of_night_vision_center || t-limit_field_of_night_vision_total || t-has_directional_bright_light<br />
|-<br />
| t-directional_bright_light_center || t-directional_bright_light_total || t-has_directional_dim_light || t-directional_dim_light_center<br />
|-<br />
| t-directional_dim_light_total || t-lightColor || || |<br />
|}<br />
<br />
'''''It is important to note that some attributes names on tokens have corresponding attribute names on characters, which represent different values. For example, [*T:id] returns the character ID, while [*T:t-id] returns the token ID.'''''<br />
<br />
=== Subroutine Parameters ===<br />
<br />
When using a gosub statement (-->) or a conditional marked as a gosub (prefixing the label with a > character), you can pass any number of parameters separated by semicolons (;) that the code in the subroutine can utilize.<br />
<br />
Subroutine parameters are numbered starting at 1, and are accessed by using the notation [%number%], so the first parameter is [%1%], the second is [%2%], etc.<br />
<br />
Parameter substitution happens on all line types, and happens prior to character attribute references or roll variable substitution.<br />
<br />
=== Campaign Attribute ===<br />
You can retrieve properties of the API's Campaign object with the [*C:attributename] syntax. For example, [*C:playerpageid] will retrieve the current player ribbon page from the Campaign object.<br />
<br />
=== Page Attributes ===<br />
If you have set the '''activepage''' parameter, you can retrieve page-related properties with the [*P:attributename] syntax, including the page's UDL parameters.<br />
<br />
=== Repeating Section Values ===<br />
<br />
You can reference repeating attribute data using the syntax [*R:attributename] syntax (similar to referencing standard character attributes). The currently active repeating row information will be used to retrieve attribute values. You can also retrieve the full attribute name for a repeating row attribute by using the [*R>attributename] notation. This is useful to pass to things like chatsetattr.<br />
<br />
=== Array Elements ===<br />
After an array has been declared, the elements can be referenced with [@arrayName(index)]. Array indices start at 0.<br />
<br />
== Deferred Resolution for Meta Scripts ==<br />
<br />
As of 1.2.9, ScriptCards supports a deferral character for use when calling another API script with via the --@ statement, to defer processing of meta script references so they get processed prior to the sub-API call insted of prior to ScriptCards execution. To defer this processing for meta script (SelectManager, Fetch) by inserting a deferral character into the meta call. For example, if I want to have ScriptCards call TokenMod as if the token for "Quej Gr'stra" (yes, I let Roll20 name my test NPCs) I could use something like this:<br />
<br />
--@token-mod|{^& select Quej Gr'stra} _on showname<br />
<br />
The "^" in between { and & will prevent SelectManager from seeing the call when the ScriptCard script is processed, but the --@ statement will remove the deferral character so the command that will be sent by ScriptCards is:<br />
<br />
!token-mod {& select Quej Gr'stra} --on showname<br />
<br />
With the deferral character removed, SelectManager will see the {& select ...} and do its magic.<br />
<br />
While the default deferral character is "^", the deferral character is a setting that can be changed:<br />
<br />
--#deferralcharacter|%<br />
<br />
Will make % the deferral character for future --@ statements in the running script.<br />
<br />
There are currently three supported Meta script structures: {^&...} for SelectManager, @^(...) and *^(...) for fetch, where the ^ in the structures here represents the placement of the deferral character.<br />
<br />
== Arrays ==<br />
<br />
Arrays are a new data type introduced in version 1.1.12 of ScriptCards, and are manipulated with associated function (--~) commands.<br />
<br />
* Arrays are a lists of strings. Items in an array cannot contain the semi-colon (;) character, as that is used to separate parameters in the function code that deals with arrays.<br />
* Arrays are accessed via the --~ script command. In some cases, the value of the tag (variable name) for array commands is not used, and can be a dummy value or simply omitted. I have omitted them in the statements below.<br />
* All commands that DO return a value return string values, even if the content is numeric.<br />
* If a command returns a value and there is some sort of reason that it isn't an array value, you will get "ArrayError" in the return value. This can happen if you reach the end of an array while stepping through it, for example, so checking for "ArrayError" can serve as the end condition for a loop.<br />
* Each array keeps track of its current index, allowing you to step forward and backwards through arrays.<br />
* Any number of arrays can be defined.<br />
* Unlike string variables and roll variables, array variables cannot (currently) be referenced directly. It is necessary to use the function (--~) syntax to manipulate arrays and get values from them as strings for use in other parts of your script.<br />
<br />
<br />
== Reentrant Scripts ==<br />
<br />
Reentrant scripts allow you to create buttons in your script code that will re-execute the script at a given label within the code. If you set the reentrant setting (--#reentrant|somevalue) to a non-zero value, your setting and variable information will be preserved between executions. Reentrant script can be used to present menus or choices and then continue acting.<br />
<br />
Reentrant buttons are created with the [rbutton]Caption::ReentryLabel;Parameter[/rbutton] construct. The caption will be displayed on the generated button. ReentryLabel is the name of a label in your script that the button will jump to when clicked, and Parameter will be passed in as a string value called "reentryval".<br />
<br />
Example:<br />
<pre><br />
!script {{<br />
--#reentrant|testing<br />
--=Roll|1d20<br />
--+Roll|[$Roll]<br />
--&String|That was a [$Roll.Raw]!<br />
--~x|array;define;MyArray;Apple;Banana;Orange<br />
--+Try it|[rbutton]Hello!::EXEC_PC_SPELL;9[/rbutton]<br />
--X|<br />
<br />
--:EXEC_PC_SPELL|<br />
--+ReentryVal|[&reentryval]<br />
--+The value of Roll is|[$Roll]<br />
--+Value of String|[&String]<br />
--+Array|[@MyArray(0)]<br />
--X|<br />
}}<br />
</pre><br />
<br />
This script sets up some variables and then displays a button labeled "Hello!". If the user clicks the button, the script will be re-entered starting at the "EXEC_PC_SPELL", which will display the content of the variables from the original execution.<br />
<br />
'''''Note: This section needs to be expanded upon'''''<br />
<br />
== Procedure Libraries ==<br />
<br />
You can now create handouts in your game in Roll 20 with the name format "ScriptCards Library NAME", where name is a name you assign to the library. Library names are case sensitive. It is my hope that the more proficient ScriptCards scripters out there will provide procedure libraries (or procedures that can be included in libraries) for others to use to make their scripting life easier. Be they specific to a game system, or to a type of activity, I think a robust set of libraries that GMs could use to enhance their scripting capabilities would be very valuable to the community. Should such things begin to emerge, I’ll create a portion of the ScriptCards Wiki page to house them.<br />
<br />
To include one or more libraries in a script, use the +++libname+++ directive (does not need a -- line associated with it). Multiple library names can be specified by separating them with semicolons (i.e., +++General;dnd5elib;Colorize+++ would include three libraries (General, dnd5elib, and Colorize).<br />
<br />
Included libraries are separated from the main script code by the automatic inclusion of "--X|" before the first library is appended to the script, and all libraries are loaded at the end of the script before script processing takes place.<br />
<br />
Procedures and labels in libraries can be used just as if they were included in the body of your script. Note that this DOES mean that you could, technically, jump into a library with a direct branch (--^) or direct branch conditional, but I recommend using libraries to store reusable procedures.<br />
The Notes section of the library handout stores the library code, and is written just like any other ScriptCards code except:<br />
<br />
* They cannot use roll queries (?{Some Prompt:}) to get information from the user at execution time.<br />
* They cannot use @{} notation to access character and token information.<br />
<br />
Both of these limitation stem from the fact that Procedure Libraries are not processed by the chat server, which is what handles these items.<br />
<br />
Here is an example of handling damage modifications (resistance, vulnerability, and immunity) in D&D 5E with a library:<br />
<br />
<pre><br />
!script {{<br />
+++dnd5elib+++<br />
--#|Damage Modifiers Test<br />
--#targettoken|@{target|token_id}<br />
-->Lib5E_CheckDamageModifiers|ResistType;fire<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] fire damage<br />
<br />
-->Lib5E_CheckDamageModifiers|ResistType;cold<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] cold damage<br />
<br />
-->Lib5E_CheckDamageModifiers|ResistType;poison<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] poison damage<br />
<br />
-->Lib5E_CheckDamageModifiers|ResistType;acid<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] acid damage<br />
<br />
--X|<br />
}}<br />
</pre><br />
<br />
Library content (In a handout called “ScriptCards Library dnd5elib” NOTE: Paste into Notepad first and then paste into the handout in Roll20 to avoid bringing over HTML formatting from the web site):<br />
<br />
<pre><br />
--/|ScriptCards Library: dnd5elib version 0.0.1<br />
--/|Provides various utility procedures for D&D 5E games<br />
<br />
--/|Lib5E_CheckDamageModifiers handle damage resistance, vulnerability, and immunity. <br />
--/|Pass a string variable to be filled with a string to be appended to a dice roll and the damage type <br />
<br />
--:Lib5E_CheckDamageModifiers|damageVariableName;damageType<br />
--&[%1%]|<br />
--?"[*T:npc_vulnerabilities]" -inc "[%2%]"|>_Lib5E_IsVulnerable;[%1%]<br />
--?"[*T:npc_resistances]" -inc "[%2%]"|>_Lib5E_IsResistant;[%1%]<br />
--?"[*T:npc_immunities]" -inc "[%2%]"|>_Lib5E_IsImmune;[%1%]<br />
--<|<br />
<br />
--:_Lib5E_IsVulnerable| --&[%1%]| * 2 [Vulnerable] --<|<br />
--:_Lib5E_IsResistant| --&[%1%]| \ 2 [Resistant] --<|<br />
--:_Lib5E_IsImmune| --&[%1%]| * 0 [Immune] --<|<br />
</pre><br />
<br />
The idea is that the functions in the library create a string that can be appended to a roll to modify the output based on resistances, so you pass Lib5E_CheckDamageModifiers the name of the string variable you want to use and the damage type. The variable (ResistType in this case) will include either nothing, “* 2 [Vulnerable]”, “\ 2 [Resistant]”, or “* 0 [Immune]” which can be included in a roll assignment (--=) to modify the damage as appropriate. The order here might be important if an NPC is misconfigured to be both resistant and immune to the same damage type. Since immune is an absolute, having it last ensures that it will override resistant or vulnerable. A creature that is both vulnerable and resistant (again, misconfigured) will come back as resistant since that condition is checked after vulnerable.<br />
Some notes: I prefix my library labels with either “Lib5E_” or “_Lib5E_” as a clarity convention. This isn’t strictly necessary but you should be aware that if two libraries (or if your script and a library) define the same label, the last label defined will win. Since libraries are appended to the end of the script in the order you include them in the +++libname+++ directive, you can somewhat control this, but it is probably best to avoid re-declaring labels. <br />
<br />
In my case, items beginning with “Lib5E_” are intended to be called by scripts, while items beginning with “_Lib5E_” are intended to be used as subroutines by the “public” procedures. Of course, there is no reason you couldn’t call them directly.<br />
<br />
You might also note that I’ve included some library information in comment lines (--/|) at the top of the library. These are ignored by ScriptCards, and are a good way to convey requirements, parameters, usage information, etc.<br />
<br />
== Example Libraries ==<br />
<br />
=== dnd5elib ===<br />
<br />
[https://github.com/kjaegers/ScriptCards Download the dnd5elib Library from the ScriptCards GitHub]<br />
<br />
The '''dnd5elib''' library provides a collection of utility procedures that help simplify dealing with the D&D 5E Official Sheet. Some of the procedures in this library require '''chatsetattr''' to be installed in your game. This is a growing library, and currently only has a handful of routines. They are:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Procedure Name !! Notes<br />
|-<br />
| style="white-space:nowrap" | Lib5E_CheckDamageModifiers || This procedure can be used to evaluate vulnerabilities, resistances, and invulnerabilities on an NPC. After setting the --#target| parameters, pass the Lib5E_CheckDamageModifiers procedure a variable name (no reference information) and a damage type (i.e., fire, cold, bludgeoning, etc.) and a string variable with the name passed in as the first parameter will be created that contains text that can be included in a roll line (--=) in order to modify the roll as appropriate. For example, '''-->Lib5E_CheckDamageModifiers|ResistType;fire''' will check the current target character's attributes for "fire" and will either return an empty string (no references), "* 0 [Immune]" if the creature is immune, "\ 2 [Resistant]" if the creature is resistant, or "* 2 [Vulnerable]" if the creature is vulnerable to fire damage.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_DeductSpellSlot || Pass in a character_id and a slot level, and the script will expend one spell slot of that level, capping the value at 0 slots remaining. For Example '''<nowiki>-->Lib5E_DeductSpellSlot|@{selected|character_id};1</nowiki>''' to deduct a first level spell slot from the selected character.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_FindResource || Used to locate a resource value on a character. Pass in a character_id, a resource name, and two variable names. The procedure will check both repeating and non-repeating resources looking for a resource whose name matches what was passed in and return three variables. The first will be a string variable named for the 3rd parameter and contains the attribute name of the resource's "name" field. The second will be a string variable named after parameter 4 and contains the resource's value field attribute name, and the third variable is a Roll Variable, also named after the 4th parameter that contains the current resource value. Example: '''<nowiki>-->Lib5E_FindResource|@{selected|character_id};Crossbow bolts;ResName;ResValue</nowiki>''' will find "Crossbow bolts" as a resource on the character and return [&ResName] which is the name of the resource attribute, [&ResValue] which is the '''name of the attribute that stores the value''' and [$ResValue] which is the current numeric value of the resource.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Global_Attack_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Attack Modifiers (repeating_tohitmod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Bless" for 1d4 active and "Being Cool" for +2 active, I will get a return string " + 1d4 [Bless] + 2 [Being Cool]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Save_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Save Modifiers (repeating_savemod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Bless" for 1d4 active and "Being Cool" for +2 active, I will get a return string " + 1d4 [Bless] + 2 [Being Cool]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Skill_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Skill Modifiers (repeating_skillmod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Guidance" for 1d4 active and "Being Cool" for +2 active, I will get a return string " + 1d4 [Guidance] + 2 [Being Cool]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_AC_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Save Modifiers (repeating_savemod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Shield of Faith" with a value of 2 active, I will get a return string " + 2 [Shield of Faith]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Damage_Modifiers || Pass a character ID and TWO string variable to set the return value. The first string will be for normal damage, and the second will be the additional damage on a crit. This procedure will look through the Global Damage Modifiers (repeating_damagemod_*) for rows that are active (checked on the character sheet) and return two strings with the dice rolls and descriptions for them (for example, if I have "Sneak Attack" with a value of 1d6 normal and 1d6 critical damage active, I will get a return string " + 1d6 [Sneak Attack]" and another string of " + 1d6 [Sneak Attack CRIT]" that can be used in a dice rolls.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_DivineSmiteDice || Used to calculate the number of dice to be rolled for a paladin's Divine Smite. Pass a target token id, a spell slot level, and a string variable to be set to the dice roll amount based on the NPC_TYPE attribute of the target token. The returned variable will contain a dice roll (like "3d8" that can be used in a --= line)<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Character_Summary || Outputs a mini character sheet, including clickable buttons for attacks, actions, legendary actions, etc. Will automatically detect a PC vs NPC and output the appropriate sections.<br />
|}<br />
<br />
Due to formatting issues with the Wiki, the library code has been moved to a [https://gist.github.com/kjaegers/52f6049ddd257f0a1288aca4bbde13c5 GITHUB GIT]. Please view the GIST in raw mode and copy the text and paste it into a handout called "ScriptCards Library dnd5elib" in your Roll20 Game.<br />
<br />
== What to Know if you are Coming from PowerCards ==<br />
<br />
''Note: This section is a work in progress.''<br />
<br />
While ScriptCards and PowerCard have very similar output goals, their internals and use are quite different. The table below summarizes some of the major differences between the scripts.<br />
<br />
::{| class="wikitable"<br />
|-<br />
! PowerCards !! ScriptCards <br />
|-<br />
| With a handful of exceptions, all lines in a PowerCard macro are intended to produce a line of output on the final card. || With ScriptCards, ONLY the <code>--+</code> and <code>--*</code> statement types produces output <br />
|-<br />
| PowerCards lines begin with two dashes (<code>--</code>) followed by a unique tag name for the line, followed by a vertical bar and the content for the line. || ScriptCards lines begin with two dashes (<code>--</code>) followed by a '''statement type identifier''', which is a single character that identifies the type of line to the interpreter. This is followed by a tag (frequently optional), a vertical bar, and the parameters for the statement being executed.<br />
|-<br />
| PowerCard macros are always processed top to bottom. Lines can be hidden so they don't output anything, but there is no looping or branching (--SkipTo looks like a branch, but it just hides all of the lines until the referenced label. || ScriptCards scripts support true branching, including direct branching (<code>--^</code>) and procedure branching (<code>--></code>) and (<code>--<</code>). Procedures support parameters and a call stack so procedures can be nested to call other procedures.<br />
|-<br />
| All lines in a PowerCards macro need to have unique tags because PowerCards builds the card as a single JavaScript object using the tag names to store what will be displayed. This is why repeated tag names always result in the last one being shown. || ScriptCards tags do not need to be unique, and in the case of many line types are optional.<br />
|-<br />
| PowerCards conditionals result in either showing or hiding the line they are on. || ScriptCards conditionals '''''only''''' support branching as the result of the comparison. This branching can be direct (a GOTO) or procedural (a GOSUB) '''''NOTE: As of version 1.2.0, ScriptCards also supports roll/string variable assignment as a result of conditional evaluation'''''<br />
|-<br />
| PowerCards relies on the Roll20 [[Quantum Roll]] server and inline rolls for all dice functions || ScriptCards includes its own dice roll parser, and '''''does not support''''' inline rolls.<br />
|-<br />
| PowerCards RollIDs (often mistaken for variables) are assigned by analyzing the results of an inline roll, and cannot be referenced in other rolls, so you can't roll a <code>1d4</code> and then roll a <code>1d20</code> and add the <code>1d4</code> result because all of the rolls happen on the chat server before PowerCards gets the macro text. || ScriptCards supports two types of variables: Roll Variables and String Variables. Because ScriptCards uses its own roll parser and is not dependent upon the chat server, rolls and their results can be used in other rolls, math functions, output, etc.<br />
|}<br />
<br />
== Example Scripts ==<br />
<br />
Below are some sample scripts that utilize the various statement types in ScriptCards:<br />
<br />
=== Divine Smite ===<br />
<br />
This script will prompt the user for a spell slot level to expend on a divine smite. It will check the target's npc_type to see if it is an Undead or Fiend, which adds an additional d8 to the smite roll.<br />
<br />
[[File:ScriptCards Divine Smite.png|Divine Smite Script Output]]<br />
<br />
<pre><br />
!scriptcard {{<br />
--#title|Divine Smite<br />
--=DiceCount|?{Spell Slot Level?|1|2|3|4|5|6|7|8|9} + 1<br />
--=IsFiendOrUndead|0<br />
--?"@{target|npc_type}" -inc fiend|>IsBoosted<br />
--?"@{target|npc_type}" -inc undead|>IsBoosted<br />
--=TotalDice|[$DiceCount] + [$IsFiendOrUndead]<br />
--=SmiteRoll|[$TotalDice]d8<br />
--#emoteText|@{selected|token_name} smites @{target|token_name}<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
--+Smite|deals [$SmiteRoll] radiant damage.<br />
--X|<br />
<br />
--:IsBoosted|<br />
--=IsFiendOrUndead|1<br />
--<|<br />
}}<br />
</pre><br />
<br />
==== How It Works ====<br />
<br />
The first line sets the "title" card parameter to "Divine Smite".<br />
<br />
Line 2 Shows a query to the user asking for the spell slot level, adds one and stores the value in the "DiceCount" Roll Variable. The query/dropdown is generated by the chat server prior to the script being executed.<br />
<br />
Line 3 defaults the "IsFiendOrUndead" Roll Variable to 0.<br />
<br />
Lines 4 and 5 compare the target's "npc_type" attribute (passed by the chat server as text) to see if they include either "undead" or "fiend". If true, the IsBoosted subroutine will be called. No parameters are passed to this subroutine.<br />
<br />
Line 6 sets the "TotalDice" variable to the base (DiceCount) number plus the IsFiendOrUndead number, which will be a 0 or a 1.<br />
<br />
Line 7 calculates "SmiteRoll" by rolling a number of d8 equal to the "TotalDice" value.<br />
<br />
Lines 8-10 set the parameters for the emote, which appears above the card content. By setting the sourceToken and the targetToken, their icons will appear in the emote surrounding the text describing the action.<br />
<br />
Line 11 is the only line that actually produces output on the card. It results in "Smite deals # radiant damage".<br />
<br />
Line 12 ends the script execution, preventing the script from continuing and running the subroutines out of context.<br />
<br />
Lines 14-16 are the IsBoosted subroutine, starting with the :IsBoosted label. The IsFiendOrUndead variable is set to 1, and a return from subroutine is executed.<br />
<br />
=== Magic Missile ===<br />
<br />
This script demonstrates using a loop and calling a subroutine to fire a number of missiles determine by the spell slot level used to cast the spell.<br />
<br />
[[File:ScriptCards_MagicMissile_Fixed.png|Magic Missile Script Output]]<br />
<br />
<pre><br />
!scriptcard {{ <br />
--#title|Magic Missile<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
--=MissileCount|?{Spell Slot Level?|1|2|3|4|5|6|7|8|9} + 2<br />
--=DisplayCount|1<br />
--=MissileDamage|0<br />
--#leftsub|Slot level ?{Spell Slot Level?}<br />
--#rightsub|Ranged Attack<br />
--#emoteText|Fred uses a level ?{Spell Slot Level?} spell slot to fire [$MissileCount.Total] missiles of magical force!<br />
--:MissileLoop|<br />
-->FireMissile|<br />
--=DisplayCount|[$DisplayCount] + 1<br />
--?[$DisplayCount] -le [$MissileCount]|MissileLoop<br />
--+Total|Total damage is [$MissileDamage]<br />
--X|<br />
<br />
--:FireMissile|<br />
--=ThisMissile|1d4 + 1<br />
--=MissileDamage|[$MissileDamage] + [$ThisMissile]<br />
--+Missile|[$DisplayCount.Total] Hits for [$ThisMissile] [b]force[/b] damage<br />
--<|<br />
}}<br />
</pre><br />
<br />
==== How It Works ====<br />
<br />
Lines 1-3 set the card title, the source token and the target token. Setting these tokens causes their icons/avatars to appear in the Emote section of the card.<br />
<br />
Line 4 asks the user what spell slot level they wish to use to cast magic missile. The number of missiles fired is equal to 2 plus the spell level, and this is stored in the MissileCount variable.<br />
<br />
Line 5 stores a 1 in the DisplayCount variable. This will be used to control the loop to determine the number of missiles fired and the missile number when displaying damage rolls.<br />
<br />
Line 6 initializes MissileDamage to 0<br />
<br />
Line 7 sets the left subtitle to the text "Slot Level #", where # is the spell slot level being used.<br />
<br />
Line 8 sets the right subtitle to the text "Ranged Attack".<br />
<br />
Line 9 sets the emoteText parameter with a description of the action, including the slot level and number of missiles fired.<br />
<br />
Line 10 is a label for the missile firing loop<br />
<br />
Line 11 Calls the "FireMissile" subroutine<br />
<br />
Line 12 increases the DisplayCount variable by 1<br />
<br />
Line 13 Checks to see if there are still missles to fire (DisplayCount <= MissileCount) and if so branches to MissileLoop<br />
<br />
Line 14 Displays the total damage dealt by the spell.<br />
<br />
Line 15 stops execution of the script to prevent out of context execution of the subroutine.<br />
<br />
Lines 76-21 are the FireMissile subroutine, beginning with the FireMissile label. The 1d4+1 is rolled and assigned to "ThisMissile". The result is added to the existing MissileDamage total, and a line for the current missile is displayed with the missile number and the damage for the missile.<br />
<br />
=== Longsword Attack ===<br />
<br />
This script demonstrates a standard 5E D&D melee weapon attack, including detection of misses, fumbles, hits, and critical hits. If installed, alterbars is used to decrement the target's BAR3 value by the damage dealt.<br />
<br />
[[File:ScriptCards Longsword.png|Longsword Script Output]]<br />
<br />
<pre><br />
!scriptcard {{<br />
--#title|Longsword<br />
--#leftsub|Melee Attack<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
--#emoteText|@{selected|token_name} attacks @{target|token_name}<br />
--=TargetAC|@{target|npc_ac}<br />
--?[$TargetAC.Total] -gt 0|DoneWithAC<br />
--=TargetAC|@{target|ac}<br />
--:DoneWithAC|<br />
--=AttackRoll|1d20 + @{selected|strength_mod} [STR] + @{selected|pb} [PROF]<br />
--+Attack|@{selected|token_name} rolls [$AttackRoll] vs AC [$TargetAC].<br />
--?[$AttackRoll.Base] -eq 20|Crit<br />
--?[$AttackRoll.Base] -eq 1|Fumble<br />
--?[$AttackRoll.Total] -ge [$TargetAC.Total]|Hit<br />
--+Miss|The attack missed.<br />
--^Final|<br />
<br />
--:Fumble|<br />
--+Fumble!|The attack went horribly wrong.<br />
--^Final|<br />
<br />
--:Hit|<br />
--=Damage|1d8 + @{selected|strength_mod} [STR]<br />
--+Hit!|The attack hit @{target|token_name} for [$Damage] slashing damage.<br />
--@alter|_target|@{target|token_id} _bar|3 _amount|-[$Damage]<br />
--^Final|<br />
<br />
--:Crit|<br />
--=Damage|1d8 + @{selected|strength_mod} [STR] + 1d8 [CRIT]<br />
--+Critical Hit!|The attack hit @{target|token_name} for [$Damage] slashing damage.<br />
--@alter|_target|@{target|token_id} _bar|3 _amount|-[$Damage]<br />
<br />
--:Final|<br />
}}<br />
</pre><br />
<br />
==== How it Works ====<br />
<br />
In lines 1-5, we set the title, subtitle, and emote text along with the tokens for the emote area.<br />
<br />
Lines 6-9 allow us to determine the AC of the target. On the 5E Roll20 sheet, NPCs armor class is stored in "npc_ac", while PCs armor class is in "ac". First we grab npc_ac and if it is zero, we check AC.<br />
<br />
Line 10 rolls the attack roll, rolling 1d20 and adding the attacker's strength modifier and proficiency bonus<br />
<br />
Line 11 displays the result of the attack roll on the card<br />
<br />
Lines 12-14 determine what kind of result the attack had. If the .Base value of the roll was 20, we branch to "Crit". If it was 1, we branch to "Fumble". If the .Total value of the roll was greater than or equal to the AC that was determined in Lines 6-9, we branch to Hit.<br />
<br />
Assuming we didn't branc anywhere, the result of the attack was a miss, so we display that on line 15 and then branch to "Final"<br />
<br />
This is followed by three branch segments, :Fumble, :Hit, and :Crit. A fumble displays a text message and branches to :Final.<br />
<br />
On a hit or a crit, we roll Damage (adding additional damage dice on a crit). We display a "Hit!" or "Critical Hit!" message and then make an API call to AlterBars, passing it the token id, bar we want to modify (3 in this case), and the amount we want to modify by the Damage value.<br />
<br />
=== Party Health Status ===<br />
<br />
This example calculates the current Hit Points remaining and HP percentage for each character and creates a color-coded display with the current party status.<br />
<br />
[[File:ScriptCards Party Health.png]]<br />
<br />
<pre><br />
!scriptcard {{<br />
--#title|Party Status<br />
--#titleCardBackground|#33CC33<br />
--#oddrowbackground|#bfee90<br />
--#evenrowbackground|#90eebf<br />
-->HealthCheck|@{Quej Grastra|character_id}<br />
-->HealthCheck|@{Brim Cheuto|character_id}<br />
-->HealthCheck|@{Odug Ututees|character_id}<br />
--X|End of card Execution<br />
<br />
--:HealthCheck|<br />
--=HealthPerc|[*[%1%]:hp] / [*[%1%]:hp^] * 100 \ 1<br />
--=HealthColor|000000<br />
--?[$HealthPerc.Total] -gt 50|HealthSkip<br />
--=HealthColor|FF0000<br />
--:HealthSkip|<br />
--+[*[%1%]:character_name]|has [#[$HealthColor.RollText]][*[%1%]:hp] of [*[%1%]:hp^][/#] HP [R]([$HealthPerc.Total]%)[/R]<br />
--<|End of HealthCheck<br />
}}<br />
</pre><br />
<br />
==== How it Works ====<br />
<br />
Lines 1-4, we set the card title, and set the title background and row background colors to shades of green.<br />
<br />
Lines 5-7 make gosub calls the the "HealthCheck" subroutine, passing in the character ID of each of the named characters (these are the names of the characters in my test game)<br />
<br />
Line 8 terminates the script execution.<br />
<br />
The remaining lines of the script are the HealthCheck subroutine, which works like this:<br />
<br />
Line 10 is the subroutine label (:HealthCheck)<br />
<br />
Line 11 uses the character id passed as a parameter and combines it with character attribute lookup *(...) to retrieve the value of "hp" and "hp<nowiki>^</nowiki>" for the character. The <nowiki>^</nowiki> character is used to specify that we want the MAX value for this attribute for the second call. We divide these two numbers and multiple by 100 to get a percentage. Finally, we use integer division by 1 to round the percentage and drop the decimals. The end result gets stored in the HealthPerc roll variable.<br />
<br />
Line 12 defaults to color of the health text to black<br />
<br />
Line 13 check to see if the health percentage is greater than 50. If so, it branches to HealthSkip, preventing the script from executing line 13.<br />
<br />
Line 14 sets the color of the health text to red<br />
<br />
Line 15 is the label that will be branched to from Line 13 to skip the red coloring<br />
<br />
Line 16 again uses character attribute substitution and the passed parameter value to output a display line containing the character name, the colorized health total, and the percentage value. The percentage is right-justified.<br />
<br />
Line 17 returns from the HealthCheck subroutine.<br />
<br />
=== Expanded Magic Missile Script ===<br />
<br />
This is the expanded and enhanced version of the Magic Missile script covered in {{yt|watch?v=u50xvNzS9Zk | this video}}. It includes visual and audio effects, checking and deducting spell slots, and applying damage using either Token-Mod or Alterbars.<br />
<br />
<pre><br />
!scriptcard {{ <br />
--#title|Magic Missile<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
<br />
-->GetAndCheckSlotInformation|<br />
<br />
--=MissileCount|[$SlotLevel] + 2<br />
--=DisplayCount|1<br />
--=MissileDamage|0<br />
--#leftsub|Slot level [$SlotLevel]<br />
--#rightsub|Ranged Attack<br />
--#emoteText|@{selected|character_name} uses a level [$SlotLevel.Total] spell slot to fire [$MissileCount.Total] missiles of magical force!<br />
<br />
--:MissileLoop|<br />
-->FireMissile|<br />
--=DisplayCount|[$DisplayCount] + 1<br />
--?[$DisplayCount] -le [$MissileCount]|MissileLoop<br />
--+Total|Total damage is [$MissileDamage]<br />
-->DeductSpellSlot|<br />
--#rightsub|Level [$SlotLevel] Left: [$SlotsRemaining] <br />
-->PlayEffects|none;burst-smoke;beam-magic;spell_01<br />
-->ApplyDamageTokenmod|@{target|token_id};3;-[$MissileDamage]<br />
-->ApplyDamageAlterbars|@{target|token_id};3;-[$MissileDamage]<br />
--X|<br />
<br />
--:FireMissile|<br />
--=ThisMissile|1d4 + 1<br />
--=MissileDamage|[$MissileDamage] + [$ThisMissile]<br />
--+Missile|[$DisplayCount.Total] Hits for [$ThisMissile] [b]force[/b] damage<br />
--<|<br />
<br />
--:GetAndCheckSlotInformation|<br />
--=SlotLevel|?{Spell Slot Level?|1|2|3|4|5|6|7|8|9}<br />
--=SlotsTotal|[*S:lvl[$SlotLevel]_slots_total]<br />
--=SlotsExpended|[*S:lvl[$SlotLevel]_slots_expended]<br />
--?[$SlotsExpended.Total] -ge [$SlotsTotal.Total]|NoSlotsLeft<br />
--<|<br />
<br />
--:NoSlotsLeft|<br />
--+|[*S:character_name] has no level [$SlotLevel.Total] spell slots available.<br />
--X|<br />
<br />
--:DeductSpellSlot|<br />
--=SlotsExpended|[$SlotsExpended] + 1<br />
--@setattr|_charid [*S:character_id] _lvl[$SlotLevel]_slots_expended|[$SlotsExpended] _silent<br />
--=SlotsRemaining|[$SlotsTotal] - [$SlotsExpended]<br />
--<|<br />
<br />
--:PlayEffects|Parameters are : source effect; target effect; line effect; sound effect<br />
--vtoken|@{selected|token_id} [%1%]<br />
--vtoken|@{target|token_id} [%2%]<br />
--vbetweentokens|@{selected|token_id} @{target|token_id} [%3%]<br />
--@roll20AM|_audio,play,nomenu|[%4%]<br />
--<|<br />
<br />
--:ApplyDamageTokenmod|Parameters are tokenid;bar#;amount<br />
--@token-mod|_ignore-selected _ids [%1%] _set bar[%2%]_value|[%3%]<br />
--<|<br />
<br />
--:ApplyDamageAlterbars|<br />
--@alter|_target|[%1%] _bar|[%2%] _amount|[%3%]<br />
--<|<br />
}}<br />
</pre><br />
<br />
[[Category:Featured articles]]</div>5004103https://wiki.roll20.net/Script:ScriptCardsScript:ScriptCards2021-09-27T13:52:41Z<p>5004103: /* Character/Token Attributes */</p>
<hr />
<div>{{revdate}}<br />
== Introduction ==<br />
'''ScriptCards''' provides a script interpreter that can be used to create powerful macros that display the results of player/NPC actions, or display other information in a pleasing visual format in your game's chat window. The scripting language contains variables (both dice-roll (enhanced numerics) and strings) as well, conditionals, branching, subroutines with parameters, and a set of built-in functions to simplify working with Roll20 information.<br />
{{script overview<br />
|name=ScriptCards<br />
|author={{user profile|2365448|Kurt J.}}<br />
|code=<br />
|version=1.4.0e<br />
|lastmodified=2021-09-24}}<br />
ScriptCards is not game-system specific, and can be used with any system/sheet. Near the end of this Wiki there is a section set aside for libraries that can implement system-specific tasks, with the hope that enthusiasts playing particular systems will create and share utility functions that can be utilized by the wider community.<br />
<br />
The default display style for ScriptCards output is similar to the format used to document player and NPC abilities in Dungeons and Dragons 4th Edition, but does not have any system ties to D&D4E.<br />
<br />
Current OneClick Version : 1.4.0e<br />
<br />
Current Development Version : 1.4.4<br />
<br />
'''''<big>Critically Important: ScriptCards does not use/parse inline rolls. ScriptCards includes its own built-in dice roll parser to allow for the use of variables inside dice rolls. As of version 1.2.3, ScriptCards will now take inline rolls and substitute the total result value in statement strings, meaning that you can utilize inline rolls but ScriptCards will only see the result of the roll, and not parse the roll components itself.</big>'''''<br />
<br />
* {{fpl|9752053/ ScriptCards thread}}<br />
** {{fpl|10000297/ Scritpcard API Working and Sharing}}<br />
* https://github.com/kjaegers/ScriptCards/tree/main/ScriptCards_API - GitHub repository for source before the one-click version is updated.<br />
* {{yt.be|hyR7Jnq4mQM ScriptCards Intro}} 45min, Jan 2021<br />
* {{yt.be|u50xvNzS9Zk ScriptCards Magic Missile Deep Dive}} 39min, Feb 2021<br />
<br />
<br />
__TOC__<br />
=== Is ScriptCards Related to [[PowerCards]]? ===<br />
<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
Check the '''[[#What to Know if you are Coming from PowerCards|What to Know if you are Coming from PowerCards]]'''-section for a comparison table between the two scripts.<br />
<br />
== What is a ScriptCard Script ==<br />
<br />
A ScriptCard Script is text written into the chat window (either typed directly, pasted, or run via a macro) that will produce a card of information in the [[text Chat|chat window]]. A ScriptCard Script is composed of an [[API]] command: <code><nowiki>!scriptcard {{ }}</nowiki></code> enclosing any number of lines that determine the output that will be added to the card. At it simplest, the following macro:<br />
<br />
<pre>!scriptcard {{ }}</pre><br />
<br />
Will produce just a title card that displays “ScriptCards” as the name:<br />
<br />
[[File:Scriptcard blank.png]]<br />
<br />
Of course, this is just the simplest type of macro and isn’t very useful. In order to produce useful output, we need to include lines between the <code><nowiki>{{</nowiki></code> and <code><nowiki>}}</nowiki></code> that direct the API script as to what it should do.<br />
<br />
== Structure of a ScriptCard Line ==<br />
<br />
All ScriptCard lines begin with two dashes, followed by an ''statement identifier character'' that lets ScriptCards what type of line it is. There are several of these, and they are detailed in the next section. After the line type identifier, a Tag name 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.<br />
<br />
Following the Tag is a vertical bar, and then the content of the line itself. Again, each type of line might interpret this content differently.<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Identifier !! Statement Type !! Tag !! Content !! Notes<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--/</nowiki> || Comment || unused || unused || The <code>--/</code> 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--#</nowiki> || 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").<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--+</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--=</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--&</nowiki> || Assign String 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. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--@</nowiki> || 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 (i.e., [[TokenMod|!token-mod]], or [[ChatSetAttr|!setattr]], etc.)<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--:</nowiki> || 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<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--^</nowiki> || Branch To || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--></nowiki> || Call Procedure || 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<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--<</nowiki> || 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.<br />
|- <br />
| style="white-space:nowrap" | <nowiki>--?</nowiki> || Conditional Branch || Condition to be evaluated || True Branch Label<nowiki>|</nowiki>False Branch Label || The condition will be evaluated and execution will jump to one of the two indicated branches (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 included a semicolon separated list of parameters. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--s</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--l</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--v</nowiki> || 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+'''''<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--e</nowiki> || Echo to Chat || Name to send chat command as || Chat message to send || Variable substitution takes place on the tag and content.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--R</nowiki> || Retrieve Repeating Section Row information || "find", "first", or "next" || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--~</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--c</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--i</nowiki> || Information Request || User Prompt;Button Caption || InfoType;VariableName;ParameterText || See full documentation below.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--d</nowiki> || 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. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--%</nowiki> || 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. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--*</nowiki> || 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.<br />
|}<br />
<br />
== ScriptCard Statement Type Details ==<br />
The sections below detail the individual statement types supported by ScriptCards<br />
<br />
=== Comment (--/) ===<br />
<br />
A --/ statement is ignored by the ScriptCards parser. You can use this type of statement to add comments and informational text to your script. <br />
<br />
Example:<br />
<pre><br />
!script {{<br />
--/|Script Name : Fireball<br />
--/|Purpose : Allow the player to cast a fireball and blow stuff up!<br />
.<br />
.<br />
.<br />
}}<br />
</pre><br />
<br />
=== Set Parameter (--#) ===<br />
<br />
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.<br />
<br />
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.<br />
<br />
'''''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.'''''<br />
<br />
Examples:<br />
<pre><br />
--#title|Magic Missile<br />
--#leftsub|Level 1 Spell<br />
--#rightsub|Force Damage<br />
</pre><br />
<br />
The three examples above set the “title”, “leftsub”, and “rightsub” values for the card to the content value for the line. <br />
<br />
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.<br />
Settings Lines do not produce output lines on the card.<br />
<br />
The following settings are available (note that parameter names are ''not'' case sensitive):<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Name !! Effect/Use !! Default Value !! Type<br />
|-<br />
| 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<br />
|-<br />
| allowplaintextinrolls || If set to a non-zero value, plain character text in rolls will be copied to the roll text || 0 || Per-Line<br />
|-<br />
| bodyFontFace || Name of the font used in the card rows || Helvetica || Global<br />
|-<br />
| bodyFontSize || Size of the text in the card rows || 14px || Global<br />
|-<br />
| bodybackgroundimage || Specify an image (content for a CSS background-image tag) for the body area || none || Global<br />
|-<br />
| buttonBackground || Background color for buttons created with [button][/button] || #1C6EA4 || Per-Line<br />
|-<br />
| buttonBorderColor || Border (outline) color for buttons created with [button][/button] || #999999 || Per-Line<br />
|-<br />
| buttonFontFace || Font Family specifier for captions on buttons created with [button][/button] || Tahoma || Per-Line<br />
|-<br />
| buttonFontSize|| Text size for captions on buttons created with [button][/button] || x-small || Per-Line<br />
|-<br />
| buttonTextColor|| Text color of labels on buttons created with [button][/button] || #FFFFFF || Per-Line<br />
|-<br />
| 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<br />
|-<br />
| deferralcharacter || Changes the meta script deferral sequence to the specified value || ^ || Per-Line<br />
|-<br />
| diceFontColor|| Color of the dice created with the [d4] [d6], etc. formatting markers || #1C6EA4 || Per-Line<br />
|-<br />
| dicefontsize || Size of the dice created with the [d4] [d6], etc. formatting markers || 3.0em || Per-Line<br />
|-<br />
| 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<br />
|-<br />
| disablerollprocessing || If set to a non-zero value, --= lines will not process dice rolls strings || 0 || Per-Line<br />
|-<br />
| emoteBackground || Background color of the emote area || #f5f5ba || Global<br />
|-<br />
| emoteFont || Name of the font used in emote area (above the title of the output card) || Georgia || Global<br />
|-<br />
| emoteFontColor || Color of the font in the emote area || None (Empty) || Global<br />
|-<br />
| emoteFontSize || Size of the font used in the emote area || 14px || Global<br />
|-<br />
| emoteFontWeight || Font weight for the font in the emote area || bold|| Global<br />
|-<br />
| emoteState || If set to anything other than "visible", the emote portion of the card will not be displayed || visible || Global<br />
|-<br />
| emoteText || Text to display in the emote portion of the card || None (Empty) || Global<br />
|-<br />
| emotefont || Name of the font used in the emote text area || font-family: Georgia, serif; font-weight: bold; || Global<br />
|-<br />
| evenRowBackground || Hex code for the background color for even rows || #eeeeee || Per-Line<br />
|-<br />
| evenRowFontColor || Hex code for the text color for even rows || #000000 || Per-Line<br />
|-<br />
| evenrowbackgroundimage || Specify an image (content for a CSS background-image tag) for the even card rows || none || Per-Line<br />
|-<br />
| executionlimit || Maximum number of script lines the interpreter will try to execute. This prevents "infinite loop" sandbox crashes || 40000 || Global<br />
|-<br />
| hideCard || If set to any non-default value, the entire card output will be suppressed || 0 || Global<br />
|-<br />
| 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<br />
|-<br />
| 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<br />
|-<br />
| lineheight || Vertical size of each line on the output card || normal || Per-Line<br />
|-<br />
| nominmaxhighlight || If set to anything other than "0", rolls will not display crit/fumble/mixed highlight colors. || 0 || Per-Line<br />
|-<br />
| norollhighlight || If set to anything other than "0", rolls will not be formatted (plain numbers) but will still get a tooltip with details ('''''v1.3.6b+''''') || 0 || Per-Line<br />
|-<br />
| oddRowBackground || Hex code for the background color for even rows || #d0e4f5 || Per-Line <br />
|-<br />
| oddRowFontColor || Hex code for the text color for odd rows || #000000 || Per-Line<br />
|-<br />
| oddrowbackgroundimage || Specify an image (content for a CSS background-image tag) for the odd crd rows || none || Per-Line<br />
|-<br />
| reentrant || Used to name a script for rentrant button use || 0 || Global<br />
|-<br />
| 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)0 || Global<br />
|-<br />
| rollhilightlineheight || Determines the height of the hilight box placed around roll results ('''''1.4.2+''''') || 1.0em || Per-Line<br />
|-<br />
| roundUp || If set to a non-default value, integer division will round up instead of down || 0 || Per-Line<br />
|-<br />
| showfromfornonwhispers || If set to a non-zero value, will include the sender on cards that aren't whispered || 0 || Global<br />
|-<br />
| 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<br />
|-<br />
| subtitleFontColor || Color of the text in the subtitle areas || #FFFFFF || Global<br />
|-<br />
| subtitleFontFace || Name of the font used on the subtitle sections || Tahoma || Global<br />
|-<br />
| subtitleFontSize || Size of the subtitle font || 13px || Global<br />
|-<br />
| subtitleSeperator || The character(s) that will be placed between leftsub and rightsub || <nowiki>&#x2666</nowiki>; || Global<br />
|-<br />
| tableBorderRadius || CSS specifier for how rounded the borders of the output card are. Use "0px;" for square borders || 6px; || Global<br />
|-<br />
| tableShadow || CSS specifier for the drop shadow under the output card || 5px 3px 3px 0px #aaa; || Global<br />
|-<br />
| tablebgcolor || Background color of the whole card. '''''Normally not visible''''' || #EEEEEE || Global<br />
|-<br />
| tableborder || Color of the border that surrounds the whole card || 2px solid #000000; || Global<br />
|-<br />
| 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<br />
|-<br />
| timezone || IANA Specifier for the local time zone, used in system/date functions || merica/New_York || Per-Line<br />
|-<br />
| title || Text displayed in the title area of the card || ScriptCards || Global<br />
|-<br />
| titleCardBackground || A hex color code representing the background color of the title area. || #1c6ea4 || Global<br />
|-<br />
| titleFontColor || Color of the text on the card title || #FFFFFF || Global<br />
|-<br />
| titleFontFace || Name of the font used on the title area || Contrail One || Global<br />
|-<br />
| titleFontLineHeight || Line spacing on the title area || 1.2em || Global<br />
|-<br />
| titleFontSize || Size of the title font || 1.2em || Global<br />
|-<br />
| titlecardbackgroundimage || Specify an image (content for a CSS background-image tag) for the title card area || none || Global<br />
|-<br />
| titlecardbottomborder || Border CSS specifier for the bottom of the title card area || 2px solid #444444; || Global<br />
|-<br />
| titlecardgradient || If set to non-zero value, will place a vertical gradient on the title card area || 0 || Global<br />
|-<br />
| usehollowdice || If set to a non-zero value, the hollow/outline versions of the dice fonts will be used || 0 || Per-Line<br />
|-<br />
| whisper|| Comma separated list of who to whisper the output to. Use "gm" for [[GM|GMs]] and "self" for the sender || none || Global|}<br />
|}<br />
<br />
''Setting Lines do not produce output lines on the card''<br />
<br />
=== Direct Output (--+) ===<br />
<br />
A direct output line display 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.<br />
<br />
Examples of Direct Output lines:<br />
<pre><br />
--+Hello|World<br />
--+Attack|The monster rolls [$Attack] to hit!<br />
--+Damage|@{target|token_name} is hit for [$Damage] [#3333AA][b]frost[/b][/#] damage.<br />
</pre><br />
<br />
Direct Output lines support inline formatting, roll variable replacement, character attribute references, and procedure variables.<br />
<br />
=== GM Output (--*) ===<br />
<br />
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. <br />
<br />
Example:<br />
<pre><br />
--+PlayerLine|This line is shown on the public card<br />
--*GMLine|This line will only be shown to GMs, on a separate card.<br />
</pre><br />
<br />
=== Roll Variable Assignment (--=) ===<br />
<br />
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.<br />
<br />
'''''All components of a roll equation should be separated with spaces.'''''<br />
<br />
Examples:<br />
<pre><br />
--=MissileDamage|1d4 + 1<br />
--=Attack|1d20 + @{selected|strength_mod} [STR] + @{selected|pb} [PROF]<br />
</pre><br />
<br />
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. Text enclosed in square brackets ([]) is considered "flavor text" and will be added to the result text but does not impact the roll result.<br />
<br />
The following dice formats are supported:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Format Pattern !! Example !! Description<br />
|-<br />
| XdY || 3d8 || Simple format. Roll a Y-sided die X times<br />
|-<br />
| XdYkhZ || 2d20kh1 || Roll Y-sided die X times and keep the highest Z number of dice<br />
|-<br />
| XdYklZ || 4d6kl3 || Roll Y-sided die X times and keep the lowest Z number of dice <br />
|-<br />
| XdY>Z || 5d6>3 || Roll Y-sided die X times and count a 1 for each roll greater than Z <br />
|-<br />
| XdY<Z || 5d6<3 || Roll Y-sided die X times and count a 1 for each roll less than Z <br />
|}<br />
<br />
'''''Note: The dice formulae below are supported in the development version of ScriptCards and will be merged with the table above when activated on OneClick'''''<br />
::{| class="wikitable"<br />
|-<br />
! Format Pattern !! Example !! Description<br />
|-<br />
| 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<br />
|-<br />
| 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<br />
|-<br />
| 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)<br />
|-<br />
| 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<br />
|}<br />
<br />
The following operators are supported in a roll equation:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Operator !! Operation<br />
|-<br />
| + || Addition <br />
|-<br />
| - || Subtraction <br />
|-<br />
| * || Multiplication <br />
|-<br />
| / || Division <br />
|-<br />
| \ || Integer Division (Rounds down) <br />
|-<br />
| % || Modulo (Remainder of Divison)<br />
|}<br />
<br />
Roll Variables can be accessed at any time after they have been created by using the [$VariableName] format, with the following optional modifiers:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Modifier !! Meaning<br />
|-<br />
| No modifier || In a Direct Output Line (<nowiki>--+</nowiki>) 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<br />
|-<br />
| .Total || The end result of the roll equation as an unformatted number <br />
|-<br />
| .Base || The cumulative result of any dice rolled in the Roll Text (Numeric modifiers are not included) <br />
|-<br />
| .Ones || The number of dice in the roll that came up as 1s <br />
|-<br />
| .Aces || The number of dice in the roll that came up as the maximum number on the die <br />
|-<br />
| .Odds || The number of dice in the roll that came up with an odd number <br />
|-<br />
| .Evens || The number of dice in the roll that came up with an even number <br />
|-<br />
| .RollText || The raw text of the roll that was use to generate the results <br />
|-<br />
| .Text || A text representation of the results of the roll, including the numbers rolled for each die <br />
|-<br />
| .tableEntryText || The text portion of the result of a table roll<br />
|-<br />
| .tableEntryImgURL || The image source portion of the result of a table roll<br />
|-<br />
| .tableEntryValue || Numeric value of tableEntryText (via parseInt). If a non-numeric value, will be 0<br />
|-<br />
| .Raw || The total numeric result without any formatting, even if placed somewhere formatting would normally be done. <br />
|}<br />
<br />
Examples:<br />
<pre><br />
--+Total Damage|[$MissileDamage.Total] (roll was 1d4+1)<br />
--+Base Damage|[$MissileDamage.Base] (without the +1)<br />
--=Attack|1d20 + @{selected|strength_mod} [STR] + @{selected|pb} [PROF] + [$BlessBonus] [Bless]<br />
</pre><br />
<br />
In this case, 1d4 will be rolled and stored in “BlessBonus”, which can then be used in the Attack line.<br />
<br />
'''''Mathematical Functions in Roll Expressions '''''<br />
<br />
The ScriptCards roll parser works from left to right, always maintaining a current value and applying whatever comes next to the total. The following in-line functions to the roll parser. These are:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Expression !! Meaning<br />
|-<br />
| {ABS} || Absolute Value<br />
|-<br />
| {CEIL} || Ceiling value (round up to the next whole number)<br />
|-<br />
| {FLOOR} || Floor value (round down to the next whole number)<br />
|-<br />
| {ROUND} || Round value (round up if the decimal portion is greater than 0.5, otherwise round down)<br />
|-<br />
| {NEGATE} || Multiply the value by negative one.<br />
|-<br />
| {SQRT} || Take the square root of the running value. ('''''1.4.1+''''')<br />
|-<br />
| {SQUARE} || Square the running value. ('''''1.4.2+''''')<br />
|-<br />
| {CUBEROOT} || Take the cube root of the running value. ('''''1.4.2+''''')<br />
|-<br />
| {CUBE} || Cube the running value. ('''''1.4.2+''''')<br />
|-<br />
| {SIN} || Return the SIN of running value. ('''''1.4.2+''''')<br />
|-<br />
| {COS} || Return the COS of running value. ('''''1.4.2+''''')<br />
|-<br />
| {TAN} || Return the TAN of running value. ('''''1.4.2+''''')<br />
|-<br />
| {ASIN} || Return the ASIN of running value. ('''''1.4.2+''''')<br />
|-<br />
| {ACOS} || Return the ACOS of running value. ('''''1.4.2+''''')<br />
|-<br />
| {ATAN} || Return the ATAN of running value. ('''''1.4.2+''''')<br />
|}<br />
<br />
<br />
'''''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 <nowiki>[[ ]]</nowiki> 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.<br />
<br />
'''''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.<br />
<br />
'''Rolling on Rollable Tables'''<br />
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.<br />
<br />
''Roll Variable Lines do not produce output lines on the card.''<br />
<br />
=== String Variable Assignment (--&) ===<br />
<br />
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:<br />
<br />
<pre><br />
--&MyText|Hello<br />
</pre><br />
<br />
Here, we assign the text "Hello" to the string variable named MyText. You can also append text to a string variable by prefixing the content with a + sign:<br />
<br />
<pre><br />
--&MyText|+ World<br />
</pre><br />
<br />
If run after the statement above, MyText will now contain "Hello World".<br />
<br />
String variables can be referenced using the syntax [&variablename]<br />
<br />
=== Call API (--@) ===<br />
<br />
ScriptCards can use a Call API instruction to execute other API commands. The Tag contains the API 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 API command is executed.<br />
<br />
Examples:<br />
<pre><br />
--@eh|list<br />
--@alter|_target|@{target|token_id} _bar|3 _amount|-[$Damage]<br />
</pre><br />
<br />
In the first example above, the command <code>!eh list</code> will be executed, calling [[EncounterHelper]]. In the second, {{fpl|1216260/ AlterBars}} is called to modify a token's Bar 3 value.<br />
<br />
'''''Note:''''' When ScriptCards (or any API script) runs other API 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).<br />
<br />
See [[API:Script Index]] for more options.<br />
<br />
=== Branch Label (--:) ===<br />
<br />
A branch label defines a line in your code that can be reached by one of the branching instructions (<nowiki>--^</nowiki>, <nowiki>--></nowiki>, or <nowiki>--?</nowiki>). The Tag serves as the label name, and must be unique on the card.<br />
<br />
The vertical bar (|) separator must be present, but the content portion of the line is unused and can be treated as a comment.<br />
<br />
Examples:<br />
<pre><br />
--:MyLoop|<br />
--:CriticalHit|Will jump here if we roll a critical hit!<br />
</pre><br />
<br />
''A Branch Label line does not produce an output line on the card.''<br />
<br />
=== Branch (--^) === <br />
<br />
A Branch line 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.<br />
<br />
Examples:<br />
<pre><br />
--^MyLoop|Jumps to MyLoop<br />
--^SkipCrit|We didn't crit, so skip the Crit code<br />
</pre><br />
<br />
''A Branch line does not produce an output line on the card.''<br />
<br />
=== Call Procedure (-->) ===<br />
<br />
Similar to a branch, a Call Procedure (sometimes knows 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 (<nowiki>--<</nowiki>) 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 (;).<br />
<br />
Examples:<br />
<pre><br />
-->FixFormat|#3333FF;#999999<br />
</pre><br />
<br />
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%].<br />
<br />
=== Return (--<) ===<br />
<br />
A return instruction marks the end of a Gosub procedure. 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.<br />
<br />
Examples:<br />
<pre><br />
--<|<br />
--<|End of MySub<br />
</pre><br />
<br />
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.<br />
<br />
=== Conditional Statement (--?) ===<br />
<br />
A conditional statement contains some equation in the Tag that will be evaluated. '''''If any part of the comparison can/does contain a space, it needs to be surrounded by double quotes'''''<br />
<br />
Based on the true/false result of the evaluation, one of two execution paths will be taken. These execution paths are detailed in the content section of the statement. The "if true" path is specified first (directly after the vertical bar), and the "if false" path is specified after it, also separated by a vertical bar.<br />
<br />
Example:<br />
<pre><br />
--?[$AttackRoll.Total] -ge [$TargetAC]|Hit|Miss<br />
</pre><br />
<br />
'''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.'''<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Branch Format !! Meaning<br />
|-<br />
| Label || If just a label is specified, execution will branch to that label when the comparison is matched.<br />
|-<br />
| >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 <br />
|-<br />
| =VariableName || The roll variable "VariableName" will be assigned the value following a semicolon (ex: --?1 -eq 1|=Roll;1d20)<br />
|-<br />
| &VariableName || The string variable "VariableName" will be assigned the value following a semicolon (ex: --?1 -eq 1|&Result;Hit|&Result;Miss)<br />
|-<br />
| % or %! || The current for...next loop will perform the "next" action (%) or will break out (%!) <br />
|-<br />
| [ || Code block (see below)<br />
|}<br />
<br />
Examples:<br />
<pre><br />
--?[$AttackRoll.Base] -eq 20|CriticalHit<br />
--?[$AttackRoll.Base] -eq 1|>Fumble;@{selected|dexterity_mod}<br />
--?"@{target|npc_type}" -inc "undead"|&MonsterType;Undead|&MonsterType;Not Undead<br />
--?[$Attack.Total] >= [$ArmorClass]|>Hit|>Miss<br />
</pre><br />
<br />
In the first example, if the Base value of AttackRoll is a 20 (natural 20 on the die) execution will branch to the CriticalHit label.<br />
<br />
In the second example, 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%].<br />
<br />
The third example looks for the word "undead" in the npc_type attribute of the targeted character. If it exists in the text, the MonsterType string variable will be set to "Undead", otherwise it will be set to "Not Undead". <br />
<br />
The final example would call 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.<br />
<br />
''Text that does/may contain a space should be enclosed in double quotes.''<br />
<br />
The following comparison operators are available:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Comparator !! Meaning<br />
|-<br />
| -eq || Equal To <br />
|-<br />
| -eqi || Case insensitive Equal To <br />
|-<br />
| -ne || Not Equal To <br />
|-<br />
| -nei || Case insensitive Not Equal To <br />
|-<br />
| -gt || Greater Than <br />
|-<br />
| -ge || Greater Than or Equal To <br />
|-<br />
| -lt || Less Than <br />
|-<br />
| -le || Less Than or Equal To <br />
|-<br />
| -inc || Includes (text strings). <br />
|-<br />
| -ninc || Does Not Include (text strings). <br />
|}<br />
<br />
Multi-part conditionals are supported with -and and -or as separators. For example:<br />
<br />
<pre><br />
--?[$Attack.Total] -ge @{target|npc_ac} -and [$Attack.Base] -ne 20|HitButNotCrit<br />
</pre><br />
<br />
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):<br />
<br />
true AND false OR true<br />
<br />
Will be evaluated as true. The first two (true and false) will be false, but then false OR true will be true.<br />
<br />
Conversely:<br />
<br />
true or false and false<br />
<br />
Will be false, because the first true and false will evaluate to true, and then true and false will be false.<br />
<br />
'''CODE BLOCKS'''<br />
<br />
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.<br />
<br />
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:<br />
<br />
<pre><br />
!script {{<br />
--=Roll|1d2<br />
--+Roll|[$Roll]<br />
--?[$Roll.Total] -eq 2|[<br />
--&Value|Yep!<br />
--+|We are inside the TRUE portion of the block<br />
--]|[<br />
--&Value|Nope<br />
--+|We are inside the FALSE portion of the block<br />
--]|<br />
--+After|the blocks!<br />
--+Value|[&Value]<br />
}}<br />
</pre><br />
<br />
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 --]|. <br />
<br />
At this time, blocks cannot be nested, and can only be created as part of a conditional (--[ is not a valid statement type)<br />
<br />
''A conditional statement does not produce a line of output on the card.''<br />
<br />
=== Case Statement (--c) ===<br />
<br />
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 (:). Each match condition includes a branch label that will be used if the test value matches the item. 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:<br />
<br />
<pre><br />
!script {{<br />
--#title|Case Statement Testing<br />
--=Roll|1d4<br />
--C[$Roll.Total]|1:>One;[$Roll]|2:>Two;[$Roll]|3:>Three;[$Roll]|4:>Four;[$Roll]<br />
--X|<br />
<br />
--:One| --+Value|was One ([%1%]) --<|<br />
--:Two| --+Value|was Two ([%1%]) --<|<br />
--:Three| --+Value|was Three ([%1%]) --<|<br />
--:Four| --+Value|was Four ([%1%]) --<|<br />
}}<br />
</pre><br />
<br />
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 variable as a parameter.<br />
<br />
=== Save and Load (--s and --l) ===<br />
<br />
This statement pair is used to either store (--s) or load (--l) data from persistent storage. Items stored in persistent storage remain between card rolls and between Roll20 sessions. There are two types of data that can be stored: settings and roll variables. <br />
<br />
Examples:<br />
<br />
<pre><br />
--Ssettings|GreenStyle<br />
--Srollvariables|FirstCardVars<br />
</pre><br />
<br />
In this case, the tag for the statement determines what type of item is being saved (settings or rollvariables). When saving settings, all non-default settings are written to the named setting storage value. When Roll Variables are saved, all variables that currently exist will be saved to the named storage value.<br />
<br />
Loading stored items simply requires the same command with the --l statement type:<br />
<br />
<pre><br />
--Lsettings|GreenStyle<br />
--Lrollvariables|FirstCardVars<br />
</pre><br />
<br />
When loading settings, all stored settings will be applied to the current card settings. You can override settings by changing them after the load.<br />
<br />
When loading roll variables, the saved variables will be added to (or overwrite if they have the same name) any variables on the current card. This means it is safe to create roll variables before the load statement.<br />
<br />
'''Practical Uses'''<br />
The major intended use of persistent storage is for storing card formats for use in later scripts. For example, the following script:<br />
<br />
<pre><br />
!scriptcard {{<br />
--#titlecardbackground|#22CC22<br />
--#oddrowbackground|#cceecc<br />
--#evenrowbackground|#99ee99<br />
--Ssettings|@{selected|token_name}<br />
}}<br />
</pre><br />
<br />
Would save the titlecardbackground, oddrowbackground, and evenrowbackground settings to a saved list named after the selected token's name. When creating cards for that token to run later, you could include the line:<br />
<br />
<pre><br />
--Lsettings|@{selected|token_name}<br />
</pre><br />
<br />
To load all of the settings at once. By creating these setting sets for each character, you can specify a different color scheme for each character that can then be used in cards with a single formatting line.<br />
<br />
There is a supplemental ! command added to support saved settings:<br />
<br />
<pre><br />
!sc-liststoredsettings<br />
</pre><br />
<br />
Will produce a list of all stored setting names, with buttons to list the setting values stored in each group and a button to delete groups as needed.<br />
<br />
=== Visual Effects (--v) ===<br />
<br />
The --v statement can be used to create visual effects on the tabletop. The tag portion of the statement can be either "token" or "betweentokens". The content portion of the statement contains the required parameters for the effect generation, separated by spaces. If the effect is "none", no effect will be played. If any other value that doesn't match a Roll20 effect name will result in a burst-fire effect.<br />
<br />
For "token" effects, the parameters are the token id for the token the effect happens on, followed by the effect specifier.<br />
<br />
Example:<br />
<pre><br />
--vtoken|@{selected|token_id} burst-fire<br />
</pre><br />
<br />
For "betweentoken" effects, the parameters are the source token id, the target token id, and the effect specifier.<br />
<br />
Example:<br />
<pre><br />
--vbetweentokens|@{selected|token_id} @{target|token_id} beam-magic<br />
</pre><br />
<br />
'''''Version 1.2.8+'''''<br />
<br />
An additional effect specifier, "point" is available in 1.2.8+. This specifier allows you to create a visual effect at a designated X/Y pixel coordinate. Future updates will add custom-vfx support to this option. The parameters are the X and Y coordinates and the effect descriptor. As of version 1.2.9, you can also use custom effect specifiers with Point effects:<br />
<br />
<pre><br />
--vpoint|150 200 burst-fire<br />
</pre><br />
<br />
=== Echo to Chat (--e) ===<br />
<br />
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.<br />
<br />
Example:<br />
<pre><br />
--eThe Ghost|/em hovers around @{selected|character_name}... BOO!<br />
</pre><br />
<br />
Would output "The Ghost hovers around (charactername)... BOO!" as an emote to chat.<br />
<br />
=== Repeating Section Access (--R) ===<br />
<br />
ScriptCards (as of v0.0.13) supports accessing repeating section rows on a character sheet with the --R statement type. <br />
<br />
There are three basic commands you can use with --R, and they are specified by the tag used:<br />
<br />
<pre><br />
--Rfind|characterid;EntryName;SectionPrefix;SearchField<br />
</pre><br />
<br />
This is the most direct way to access a repeating section row. Supplying the character ID, followed by what you are looking for (Greatsword, for example), followed by the character sheet's section prefix (repeating_attack), followed by the field to check what you are searching for (atkname) will load the matching section (if found) into the script parsers memory. For example:<br />
<br />
<pre><br />
--Rfind|@{selected|character_id};Greatsword;repeating_attack;atkname<br />
</pre><br />
<br />
Will look at the character's "repeating_attack" section for an entry with an atkname value equal to "Greatsword". Similarly:<br />
<br />
<pre><br />
--Rfind|@{selected|character_id};Bite;repeating_npcaction;name<br />
</pre><br />
<br />
Will look for a "Bite" action on an NPC's action list.<br />
<br />
<pre><br />
--Rfirst|characterid;section prefix<br />
</pre><br />
<br />
This form of the --R command will look at all of the entries in the specified repeating section and load the first one into memory:<br />
<br />
<pre><br />
--Rfirst|@{selected|character_id};repeating_attack<br />
</pre><br />
<br />
Would load the character's first "repeating_attack" row into memory.<br />
<br />
<pre><br />
--Rnext|<br />
</pre><br />
<br />
No parameters are required for --Rnext, which loads the next entry in the list that was obtained with "first" into memory.<br />
<br />
However a row is obtained, it will be parsed to replace any attribute references (ie, @{level}) with the corresponding character attribute.<br />
<br />
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".<br />
<br />
You can reference repeating attribute data using the syntax [*R:attributename] syntax (similar to referencing standard character attributes).<br />
<br />
Here are some examples:<br />
<br />
Display the details of the "Greatsword" PC attack:<br />
<br />
<pre><br />
!script {{<br />
--Rfind|@{selected|character_id};Greatsword;repeating_attack;atkname<br />
--+Attack Name|[*R:atkname]<br />
--+Base Damage|[*R:dmgbase]<br />
}}<br />
</pre><br />
<br />
[[File:Scriptcards repeating greatsword.png|Repeating Greatsword Attack]]<br />
<br />
List all of the actions an NPC can take (just actions, not legendary, etc.)<br />
<br />
<pre><br />
!script {{<br />
--#title|NPC Actions<br />
--#leftsub|@{selected|token_name}<br />
--Rfirst|@{selected|character_id};repeating_npcaction<br />
--:DisplayLoop|<br />
--?"[*R:name]" -eq NoRepeatingAttributeLoaded|Done<br />
--+Action:|[*R:name] [*R:attack_damage] [*R:attack_damagetype]<br />
--?"[*R:attack_damage2]" -eq ""|NoSecondaryDamage<br />
--+ |[*R:attack_damage2] [*R:attack_damagetype2]<br />
--:NoSecondaryDamage|<br />
--Rnext|<br />
-->DisplayLoop| <br />
--:Done|<br />
}}<br />
</pre><br />
<br />
[[File:Scriptcards repeating npcactions.png]]<br />
<br />
In the script above, we get the "first" repeating_npcaction and display information about it. We then execute "next" and repeat until we run into "NoRepeatingAttributeLoaded".<br />
<br />
'''''Special debugging command: dump'''''<br />
<pre><br />
--Rdump|<br />
</pre><br />
<br />
The "dump" command will list all of the attributes ScriptCards knows about for the currently loaded repeating row to the API Console Log.<br />
<br />
=== Assign Variable to Built-In Function (--~) ===<br />
<br />
ScriptCards has the ability to run a function built into the API script and return the results to a variable. Some functions return roll variables, while others return strings. See the function table below for details. The format is:<br />
<br />
--~VariableName|function;param1;param2;param3;...<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Function Name !! Parameters !! Description<br />
|-<br />
| distance || token_A_ID;token_B_ID || Calculate the Chebyshev distance in grid units between two tokens. This is the measurement scheme D&D 4E/5E use for diagonal distance measurement<br />
|-<br />
| euclideandistance || token_A_ID;token_B_ID || Calculate the Euclidean distance between two tokens. This is essentially the Pythagorean theorem in action. Returns the result in grid units.<br />
|-<br />
| euclideanpixel || token_A_ID;token_B_ID || Calculate the Euclidean distance between two tokens and returns the result is pixels instead of grid units. <br />
|-<br />
| euclideanlong || token_A_ID;token_B_ID || 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 is calculated instead of before. More accurate over long distances. <br />
|-<br />
| manhattandistance || token_A_ID;token_B_ID || Also called "taxicabdistance" (which is an acceptable function name), this measures to how-many-over, how-many-up/down distance, disallowing diagonal movement.<br />
|-<br />
| getselected || none || 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 the first selected token, VariableName2 the second, etc.<br />
|}<br />
<br />
'''''Functions with Sub Functions'''''<br />
<br />
Most ScriptCards functions are grouped into set as sub functions. The table below lists the major functions and their sub functions.<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Function Name !! Sub Function !! Parameters !! Return Type !! Description<br />
|-<br />
| array || define || arrayname;value1;value2;... || none || Creates an array called "arrayname" and adds value1, value2, etc. to the array<br />
|-<br />
| array || sort || arrayname || none || Sorts the specified array in place in ascending order<br />
|-<br />
| array || add || arrayname;value1;value2;... || none || Adds value1, value2, ... to the existing array "arrayname"<br />
|-<br />
| array || remove || arrayname;value1;value2;... || none || Removes value1, value2, ... from the existing array "arrayname". Resets the array index to 0.<br />
|-<br />
| array || replace || arrayname;currentvalue;newvalue || none || Replaces all occurrences of "currentvalue" in "arayname" with "newvalue"<br />
|-<br />
| array || setatindex || arrayname;index;newvalue || none || Replaces the array item at index "index" with "newvalue"<br />
|-<br />
| array || getindex || arrayname || stringVariable || Retrieves the current index in "arrayname" and stores it in the supplied string variable<br />
|-<br />
| array || setindex || arrayname;newindex || none || Sets the current index in array "arrayname" to "newindex"<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| array || removeat || arrayname;indexposition || none || Removes the item at index "indexposition" from "arrayname". Resets the current array index to 0.<br />
|-<br />
| array || indexof || arrayname;searchvalue || stringVariable || Searches the array "arrayname" for and item with the value of "searchvalue" and, if found, returns the index of the first matching value or "ArrayError" if not found<br />
|-<br />
| array || getlength || arrayname || stringVariable || Returns the number of items in array "arrayname"<br />
|-<br />
| array || pagetokens || arrayname;tokenid;(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. 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.)<br />
|-<br />
| 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.<br />
|-<br />
| array || stringify || arrayname || stringVariable || Returns all of the items in "arrayname" as a string separated by semicolons (;)<br />
|-<br />
| array || fromstring || arrayname || delimiter;string || Creates an array from "string", splitting "string" on "delimiter" to separate the items<br />
|-<br />
| array || statusmarkers|| arrayname;tokenid || none|| Creates an array (arrayname) of the active statusmarkers (sometimes called Token Markers) for the specified tokenid<br />
|-<br />
| math || angle || math;angle;tokenid;tokenid|| rollVariable || Calculates the angle between two tokens and returns the value in degrees<br />
|-<br />
| math || ceil || math;ceil;value || rollVariable || Rounds '''value''' up to the next integer, dropping any decimal portion of the number<br />
|-<br />
| math || clamp || math;clamp;value;lowerBound;upperBound || rollVariable || Returns '''value''', but restricted to the range of '''loweBound''' and '''upperBound'''.<br />
|-<br />
| math || floor || math;floor;value || rollVariable || Rounds '''value''' down, dropping any decimal portion of the number<br />
|-<br />
| math || max || math;max;valueA;valueB || rollVariable || Returns the larger of '''valueA''' vs '''valueB'''<br />
|-<br />
| math || min || math;min;valueA;valueB || rollVariable || Returns the smaller of '''valueA''' vs '''valueB'''<br />
|-<br />
| math || round || math;round;value || rollVariable || Rounds '''value''' to the nearest integer<br />
|-<br />
| string || length || string;length;stringValue || rollVariable || Returns the length of '''stringValue''' in characters<br />
|-<br />
| string || before || string;before;searchText;stringValue || stringVariable || Searches '''stringValue''' for '''searchText''' and returns the portion of '''stringValue''' prior to that text<br />
|-<br />
| string || after || string;after;searchText;stringValue || stringVariable || Searches '''stringValue''' for '''searchText''' and returns the portion of '''stringValue''' after that text<br />
|-<br />
| string || left || string;left;count;stringValue || stringVariable || Returns the leftmost '''count''' characters of '''stringValue'''<br />
|-<br />
| string || right || string;right;count;stringValue || stringVariable || Returns the rightmost '''count''' characters of '''stringValue'''<br />
|-<br />
| string || replace || string;replace;searchText;replaceText;stringValue || stringVariable || Replaces '''searchText''' in '''stringValue''' with '''replaceText''' and returns the resulting string<br />
|-<br />
| string || replaceall || string;replace;searchText;replaceText;stringValue || stringVariable || Replaces all intances of '''searchText''' in '''stringValue''' with '''replaceText''' and returns the resulting string '''''Requires 1.2.9+'''''<br />
|-<br />
| string || trim || string;trim;stringValue || stringVariable || Removes leading and trailing spaces from stringValue and returns the result. <br />
|-<br />
| string || substring || string;substring;start;count;stringValue || stringVariable || Returns '''count''' characters starting at '''start''' from '''stringValue'''<br />
|-<br />
| 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.<br />
|-<br />
| string || tolowercase || string;tolowercase;stringValue || stringVariable || Converts the passed string to lower case and assigns to the passed variable name. <br />
|-<br />
| string || touppercase || string || stringVariable || Converts the passed string to upper case and assigns to the passed variable name. <br />
|-<br />
| 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. <br />
|-<br />
| 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.<br />
|-<br />
| 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'''.<br />
|-<br />
| turnorder || clear || none || none || Clears all entries from the {{Turn Tracker}}/Initiative<br />
|-<br />
| turnorder || addtoken || tokenid;trackervalue || none || Adds the token represented by "tokenid" to the initiative tracker with an initiavie value of "trackervalue"<br />
|-<br />
| turnorder || replacetoken || tokenid;trackervalue || none || Replaces the token represented by "tokenid" in the initiative tracker with an initiavie value of "trackervalue". Will add the token if it doesn't exist in the tracker.<br />
|-<br />
| turnorder || removetoken || tokenid || none || Removes the token represented by "tokenid" from the initiative tracker if it exists<br />
|-<br />
| turnorder || addcustom || textlabel;trackervalue || none || Add a custom text entry to the {{Turn Tracker}}/Initiative named "textlabel" with an initiative value of "trackervalue"<br />
|-<br />
| system || date || getdatetime || stringVariable || Returns the date time in the active timezone (see settings) <br />
|-<br />
| system || date || getdate || stringVariable || Returns the date in the active timezone (see settings) <br />
|-<br />
| system || date || gettime || stringVariable || Returns the time in the active timezone (see settings)<br />
|-<br />
| system || dumpvariables || "rolls", "string", or "array" || none || Dumps all of the defined variables of the indicated type to the console log<br />
|-<br />
| system || findability || system;findability;charactername;abilityname || stringVariable || Returns the object ID of the ability on the indicated character or "AbilityNotFound"<br />
|-<br />
|}<br />
<br />
Examples:<br />
<br />
<pre><br />
--~HowFarAway|distance;@{selected|token_id};@{target|token_id}<br />
</pre><br />
<br />
Returns the distance (Chebyshev) between the selected and target tokens and stores it in "HowFarAway".<br />
<br />
<pre><br />
--SelectedDudes|getselected<br />
</pre><br />
<br />
If 5 tokens were selected, 6 variables would be created: SelectedDudesCount (with a value of 5), SelectedDudes1, SelectedDudes2, SelectedDudes3, SelectedDudes4, SelectedDudes5.<br />
<br />
=== Information Request (--i) ===<br />
<br />
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.<br />
<br />
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.<br />
<br />
After the user has clicked the button and responded to the requests, ScriptCards will resume processing the script from where it left off.<br />
<br />
Here is an example “i” line:<br />
<br />
<pre><br />
--IScriptCards needs additional information to continue;Click to select a target and provide information|t;MyNewTarget;Missile1Target||q;MyNameIs;What is your name?<br />
</pre><br />
<br />
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.<br />
<br />
Supported information request types are “t” for target token, and “q” for query.<br />
<br />
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).<br />
<br />
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:<br />
<br />
<pre><br />
q;UserName;What is your name?|Fred|Bob|Sally|Nancy<br />
</pre><br />
<br />
Would have a dropdown menu with four choices.<br />
<br />
== Inline Formatting ==<br />
<br />
Inline formatting is processed on Direct Output lines only (--+ lines) and the following inline format markup is available:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Formatting Tags !! Description<br />
|-<br />
| [b]..[/b] || Bold the text between the markers <br />
|-<br />
| [i]..[/i] || Italicize the text between the markers <br />
|-<br />
| [u]..[/u] || Underline the text between the markers <br />
|-<br />
| [s]..[/s] || Strike-Thru the text between the markers <br />
|-<br />
| [c]..[/c] || Center alignment <br />
|-<br />
| [l]..[/l] || Left alignment <br />
|-<br />
| [r]..[/r] || Right alignment <br />
|-<br />
| [j]..[/j] || Full justification alignment <br />
|-<br />
| [#xxx]..[/#] or [#xxxxxx]..[/#] || Use a 3 or 6 digit hex code to colorize the text between the markers <br />
|-<br />
| [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, <code>[img width=128 height=128]</code> )<br />
|-<br />
| [button]caption::action[/button] || Create a button with the label "caption" that performs the action defined by "action". <br />
|-<br />
| [t] || Converted to HTML table tag. Text after the "t" will be included inside the tag (width, border, etc)<br />
|-<br />
| [/t] || Converted to HTML close table tag.<br />
|-<br />
| [tr] || Converted to HTML table row tag. Text after the "tr" will be included inside the tag<br />
|-<br />
| [/tr] || Converted to HTML close table row tag.<br />
|-<br />
| [td] || Converted to HTML table cell tag. Text after the "tr" will be included inside the tag<br />
|-<br />
| [/td] || Converted to HTML close table cell tag.<br />
|}<br />
<br />
== Variables ==<br />
<br />
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. While it is possible to assign both a string and a roll variable the same name, doing so will likely result in confusion when looking at the script later, so it is not recommended.<br />
<br />
String Variables are assigned with the --& statement and are referenced using [&variableName] notation.<br />
<br />
Roll Variables are assigned with the --= statement, and the assignment value is always processed by the ScriptCards Roll Processor (resolves dice rolls, etc.)<br />
<br />
There are a handful of variables assigned automatically when a ScriptCard is executed. These are all string variables, and are:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Variable !! Value<br />
|-<br />
| SendingPlayerID || Contains the object ID of the player that sent the macro<br />
|-<br />
| SendingPlayerName || Contains the display name of the player<br />
|-<br />
| SendingPlayerColor || Contains the color code associated with the player<br />
|-<br />
| SendingPlayerSpeakingAs || The contents of the "Speaking As" dropdown window<br />
|-<br />
| SendingPlayerIsGM || Contains 1 if the player is a GM, and 0 if the player is NOT a GM<br />
|}<br />
<br />
== Arrays ==<br />
<br />
Arrays are a special type of variable, and are managed by the function (<nowiki>--~</nowiki> command). All of the array function commands follow the same pattern:<br />
<br />
<pre>--~variableName|array;subcommand;arrayname;param1;param2;param3;...</pre><br />
<br />
Not all array commands return anything to "variableName". The function table above will specify the return type of the command if any.<br />
<br />
There are a couple of different ways to create an array:<br />
<br />
The '''define''' array subcommand creates (or recreates) an array and assigns it values - one for each included parameter after the array name. For example:<br />
<br />
<pre>--~|array;define;Fruits;mango;peach;strawberry;apricot;banana;apple</pre><br />
<br />
will create an array called '''Fruits''' with 6 elements in the order listed in the command (mango, peach, etc.)<br />
<br />
You can also use two other subcommands to create arrays based on tokens:<br />
<br />
<pre>--~Count|array;pagetokens;Everybondy;@{selected|token_id}</pre><br />
<br />
and<br />
<br />
<pre>--~Count|array;selectedtokens;Selected</pre><br />
<br />
In both cases, arrays of tokens will be created, and a string variable called "Count" will be set to the number of tokens in the array. The '''pagetokens''' command returns (by default) all of the tokens on the page that contains the token passed as the parameter after the array name. You can filter the tokens that "pagetokens" includes in the array by appending an optional parameter describing the type of token you are looking for:<br />
<br />
<pre>--~Count|array;pagetokens;Everybondy;@{selected|token_id};npc</pre><br />
<br />
Will return only tokens on the page that represent characters that do not have a ''controlledby'' parameter set. The available options are "all" (default), "char", "graphic", "pc", and "npc".<br />
<br />
The '''selectedtokens''' command returns an array with all of the tokens that were selected when the script was called.<br />
<br />
You can also use an arbitrary string to create an array, specifying a delimiter with the '''fromstring''' command:<br />
<br />
<pre><br />
--&names|Fred<br />
--&names|+,Sally<br />
--&names|+,Ted<br />
--&names|+,Joyce<br />
--~|array;fromstring;,;[&names]<br />
</pre><br />
<br />
The above example builds a comma-separated string and then uses "fromstring" to create an array with 4 elements from it, specifying the comma as the delimiter.<br />
<br />
Finally, you can use the '''statusmarkers''' command to create an array with one entry for each active status marker on a specified token:<br />
<br />
<pre>--~|array;statusmarkers;Conditions;@{selected|token_id}</pre><br />
<br />
will create an array with one entry for each status active on the selected token. The array elements will be the internal name of the status (if you are using custom status marker packs, the names will be specified in the marker pack).<br />
<br />
'''Traversing Arrays'''<br />
<br />
Each array keeps track of an internal index position (starting at 0). Several commands let you manage this index:<br />
<br />
*'''getindex''' returns the current index value<br />
*'''setindex''' sets the index to the specified location in the array<br />
*'''getlength''' returns the number of elements in the array<br />
*'''indexof''' returns the index location of the specified element<br />
<br />
Other commands let you retrieve values from the array:<br />
<br />
*'''getfirst''' sets the index to 0 and returns the value at that position<br />
*'''getnext''' advances the index by 1 and returns the new current value<br />
*'''getprevious''' reduces the index by 1 and returns the new current value<br />
*'''getlast''' sets the index to the last elements in the array and returns the new current value<br />
<br />
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.<br />
<br />
'''Manipulating Array Elements'''<br />
<br />
Several array commands deal with inserting, removing, and modifying elements:<br />
<br />
*'''add''' works just like define, except that it takes an existing array and adds elements to it based on the passed parameters<br />
*'''remove''' looks for items matching each passed parameter and removes them from the indicated array if they exist<br />
*'''removeat''' allows you to specify an index location in the array and remove the element at that position<br />
*'''replace''' searches an array for a value and replaces all occurrences of it with a new value (if found)<br />
*'''sort''' sorts the elements in the array in ascending order<br />
*'''strinfigy''' returns a string variable that includes each array element separated by semicolons (;) <br />
<br />
'''Referencing Array Elements'''<br />
<br />
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.<br />
<br />
<pre><br />
!script {{<br />
--~dummy|array;pagetokens;myarray;@{selected|token_id}<br />
--~count|array;getcount;myarray<br />
--+Total:|There are [&count] graphical objects on the page<br />
--~testvar|array;getfirst;myarray<br />
--:loop|<br />
--+Value|[*[&testvar]:character_name]<br />
--~testvar|array;getnext;myarray<br />
--?[&testvar] -ne ArrayError|loop<br />
--+Loop1|Is Done!<br />
}}<br />
</pre><br />
<br />
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:<br />
<br />
<pre><br />
!script {{<br />
--~dummy|array;pagetokens;myarray;@{selected|token_id}<br />
--~count|array;getcount;myarray<br />
--+Total:|There are [&count] graphical objects on the page<br />
--%loopCounter|1;[&count]<br />
--+Value|[*[@myarray([&loopCounter])]:character_name]<br />
--%|<br />
--+Loop|Is Done!<br />
}}<br />
</pre><br />
<br />
This line : <nowiki>--+Value|[*[@myarray([&loopCounter])]:character_name]</nowiki> uses [@arrayName(index)] format (inside a [*characterid:attribute] syntax) to perform the same task as running through the loop with the index.<br />
<br />
(Note: Additional examples are on the way...)<br />
<br />
== For...Next Loops ==<br />
<br />
For...Next loops in ScriptCards are supported with the with the --% statement type. A loop is defined by starting off with:<br />
<br />
<pre><br />
--%LoopCounter|<start>;<end>;[step]<br />
</pre><br />
<br />
The start and end values are required, while the step parameter is optional. If the step is omitted, it will be assumed to be 1. A string variable named after the line tag ("LoopCounter" in the case above) will be created and will hold the current iteration value for the loop. Here is a real example:<br />
<br />
<pre><br />
--%LoopCounter|1;10;1<br />
</pre><br />
<br />
This will begin a loop identified by "LoopCounter" that will start at 1, increasing by 1 each iteration (the step) until it has completed 10 executions.<br />
<br />
The "next" statement is simply <code>--%|</code>, with no tag or parameters. This indicates to ScriptCards that it should increment the counter and go back to the beginning of the loop. Extending the example above:<br />
<br />
<pre><br />
!script {{<br />
--%LoopCounter|1;10;1<br />
--=Roll|1d20<br />
--+Loop|Counter is [&LoopCounter], roll was [$Roll]<br />
--%|<br />
}}<br />
</pre><br />
<br />
The <code>--%!|</code> sequence will break out of the loop, no matter how many iterations are remaining.<br />
<br />
The % and %! character sequences can also be used as part of a 1.2.1+ non-branching conditional to continue or break the loop:<br />
<br />
<pre><br />
--?"X[&RollInto]X" -eq "XX"|%<br />
</pre><br />
<br />
In this example, if the string variable RollInfo is empty, the loop will return to the top and continue with the next iteration, while:<br />
<br />
<pre><br />
--?"X[&RollInto]X" -eq "XX"|%!<br />
</pre><br />
<br />
Would cause the whole loop to end if the condition were true.<br />
<br />
== Referencing ==<br />
<br />
=== Roll Variables===<br />
<br />
Roll Variables can be referenced from the content portion of any line type, and from the tag portion of conditional statements. The referenced value is replaced when the line is executed.<br />
<br />
There are several modifiers that can be used to reference parts of a roll:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Modifier !! Meaning<br />
|-<br />
| No modifier || In a Direct Output Line (<nowiki>--+</nowiki>), GM Output Line (<nowiki>--*</nowiki>), or String Assignement (<nowiki>--&</nowiki>), 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<br />
|-<br />
| .Total || The end result of the roll equation. Formatting rules for "No Modifier" apply based on line type. <br />
|-<br />
| .Raw || The total value of the roll variable without any formatting, no matter what kind of line the reference is used in.<br />
|-<br />
| .Base || The cumulative result of any dice rolled in the Roll Text (Numeric modifiers are not included) <br />
|-<br />
| .Ones || The number of dice in the roll that came up as 1s <br />
|-<br />
| .Aces || The number of dice in the roll that came up as the maximum number on the die <br />
|-<br />
| .Odds || The number of dice in the roll that came up with an odd number <br />
|-<br />
| .Evens || The number of dice in the roll that came up with an even number <br />
|-<br />
| .RollText || The raw text of the roll that was use to generate the results <br />
|-<br />
| .Text || A text representation of the results of the roll, including the numbers rolled for each die <br />
|-<br />
| .tableEntryText || The text portion of the result of a table roll<br />
|-<br />
| .tableEntryImgURL || The image source portion of the result of a table roll<br />
|-<br />
| .tableEntryValue || If the tableEntryText is purely numeric, will contain the numeric value<br />
|}<br />
<br />
=== String Variables ===<br />
<br />
To reference a string variable, use the notation [&variablename]. String variables can be referenced in direct output, roll variable assignment, and string variable assignment statements.<br />
<br />
=== Character/Token Attributes ===<br />
<br />
A character or token attribute can be referenced from content portion of any type of line and is substituted when the line is executed. The general format for referencing a character attribute is [*ID:attribute]. ID can be a token ID or a character ID (these start with a dash). Additionally if you have specified a sourceToken or targetToken, you can substitute "S" or "T" for the ID (for example [*S:npc_type] will retrieve the npc_type attribute from the source token.<br />
<br />
By default, all attribute references will be pulled from the '''''character''''' object that the ID represents (either directly or by being a Token ID that represents a character).<br />
<br />
Keep in mind, that if you want to access the "max" of an attribute (for example, the max hit points), then you cannot trust the name that your roll20 character sheet shows you when you hover your mouse over the max hit points. For example, this reference will not work: [*S:hp_max]. Instead, you need to use this reference: [*S:hp^].<br />
<br />
If your ID refers to a token, token attributes can be accessed by preceding the attribute name with "t-", for example [*S:t-aura1_radius]. Supported token attributes are:<br />
<br />
{|<br />
| t-name || t-id || t-statusmarkers || t-bar1_value<br />
|-<br />
| t-bar1_max || t-bar2_value || t-bar2_max || t-bar3_value<br />
|-<br />
| t-bar3_max || t-top || t-left || t-width<br />
|-<br />
| t-height || t-rotation || t-layer || t-aura1_radius<br />
|-<br />
| t-aura1_color || t-aura2_radius || t-aura2_color || t-aura1_square<br />
|-<br />
| t-aura2_square || t-tint_color || t-light_radius || t-light_dimradius<br />
|-<br />
| t-light_angle || t-light_losangle || t-light_multiplier || t-light_otherplayers<br />
|-<br />
| t-light_hassight || t-flipv || t-fliph || t-controlledby<br />
|-<br />
| t-_cardid || t-_pageid || t-imgsrc || t-bar1_link<br />
|-<br />
| t-bar2_link || t-bar3_link || t-represents || t-layer<br />
|-<br />
| t-isdrawing || t-name || t-gmnotes || t-showname<br />
|-<br />
| t-showplayers_name || t-showplayers_bar1 || t-showplayers_bar2 || t-showplayers_bar3<br />
|-<br />
| t-showplayers_aura1 || t-showplayers_aura2 || t-playersedit_name || t-playersedit_bar1<br />
|-<br />
| t-playersedit_bar2 || t-playersedit_bar3 || t-playersedit_aura1 || t-playersedit_aura2<br />
|-<br />
| t-lastmove || t-adv_fow_view_distance || t-has_bright_light_vision || t-has_night_vision<br />
|-<br />
| t-night_vision_distance || t-emits_bright_light || t-bright_light_distance || t-emits_low_light<br />
|-<br />
| t-low_light_distance || t-has_limit_field_of_vision || t-limit_field_of_vision_center || t-limit_field_of_vision_total<br />
|-<br />
| t-has_limit_field_of_night_vision || t-limit_field_of_night_vision_center || t-limit_field_of_night_vision_total || t-has_directional_bright_light<br />
|-<br />
| t-directional_bright_light_center || t-directional_bright_light_total || t-has_directional_dim_light || t-directional_dim_light_center<br />
|-<br />
| t-directional_dim_light_total || t-lightColor || || |<br />
|}<br />
<br />
'''''It is important to note that some attributes names on tokens have corresponding attribute names on characters, which represent different values. For example, [*T:id] returns the character ID, while [*T:t-id] returns the token ID.'''''<br />
<br />
=== Subroutine Parameters ===<br />
<br />
When using a gosub statement (-->) or a conditional marked as a gosub (prefixing the label with a > character), you can pass any number of parameters separated by semicolons (;) that the code in the subroutine can utilize.<br />
<br />
Subroutine parameters are numbered starting at 1, and are accessed by using the notation [%number%], so the first parameter is [%1%], the second is [%2%], etc.<br />
<br />
Parameter substitution happens on all line types, and happens prior to character attribute references or roll variable substitution.<br />
<br />
=== Campaign Attribute ===<br />
You can retrieve properties of the API's Campaign object with the [*C:attributename] syntax. For example, [*C:playerpageid] will retrieve the current player ribbon page from the Campaign object.<br />
<br />
=== Page Attributes ===<br />
If you have set the '''activepage''' parameter, you can retrieve page-related properties with the [*P:attributename] syntax, including the page's UDL parameters.<br />
<br />
=== Repeating Section Values ===<br />
<br />
You can reference repeating attribute data using the syntax [*R:attributename] syntax (similar to referencing standard character attributes). The currently active repeating row information will be used to retrieve attribute values. You can also retrieve the full attribute name for a repeating row attribute by using the [*R>attributename] notation. This is useful to pass to things like chatsetattr.<br />
<br />
=== Array Elements ===<br />
After an array has been declared, the elements can be referenced with [@arrayName(index)]. Array indices start at 0.<br />
<br />
== Deferred Resolution for Meta Scripts ==<br />
<br />
As of 1.2.9, ScriptCards supports a deferral character for use when calling another API script with via the --@ statement, to defer processing of meta script references so they get processed prior to the sub-API call insted of prior to ScriptCards execution. To defer this processing for meta script (SelectManager, Fetch) by inserting a deferral character into the meta call. For example, if I want to have ScriptCards call TokenMod as if the token for "Quej Gr'stra" (yes, I let Roll20 name my test NPCs) I could use something like this:<br />
<br />
--@token-mod|{^& select Quej Gr'stra} _on showname<br />
<br />
The "^" in between { and & will prevent SelectManager from seeing the call when the ScriptCard script is processed, but the --@ statement will remove the deferral character so the command that will be sent by ScriptCards is:<br />
<br />
!token-mod {& select Quej Gr'stra} --on showname<br />
<br />
With the deferral character removed, SelectManager will see the {& select ...} and do its magic.<br />
<br />
While the default deferral character is "^", the deferral character is a setting that can be changed:<br />
<br />
--#deferralcharacter|%<br />
<br />
Will make % the deferral character for future --@ statements in the running script.<br />
<br />
There are currently three supported Meta script structures: {^&...} for SelectManager, @^(...) and *^(...) for fetch, where the ^ in the structures here represents the placement of the deferral character.<br />
<br />
== Arrays ==<br />
<br />
Arrays are a new data type introduced in version 1.1.12 of ScriptCards, and are manipulated with associated function (--~) commands.<br />
<br />
* Arrays are a lists of strings. Items in an array cannot contain the semi-colon (;) character, as that is used to separate parameters in the function code that deals with arrays.<br />
* Arrays are accessed via the --~ script command. In some cases, the value of the tag (variable name) for array commands is not used, and can be a dummy value or simply omitted. I have omitted them in the statements below.<br />
* All commands that DO return a value return string values, even if the content is numeric.<br />
* If a command returns a value and there is some sort of reason that it isn't an array value, you will get "ArrayError" in the return value. This can happen if you reach the end of an array while stepping through it, for example, so checking for "ArrayError" can serve as the end condition for a loop.<br />
* Each array keeps track of its current index, allowing you to step forward and backwards through arrays.<br />
* Any number of arrays can be defined.<br />
* Unlike string variables and roll variables, array variables cannot (currently) be referenced directly. It is necessary to use the function (--~) syntax to manipulate arrays and get values from them as strings for use in other parts of your script.<br />
<br />
<br />
== Reentrant Scripts ==<br />
<br />
Reentrant scripts allow you to create buttons in your script code that will re-execute the script at a given label within the code. If you set the reentrant setting (--#reentrant|somevalue) to a non-zero value, your setting and variable information will be preserved between executions. Reentrant script can be used to present menus or choices and then continue acting.<br />
<br />
Reentrant buttons are created with the [rbutton]Caption::ReentryLabel;Parameter[/rbutton] construct. The caption will be displayed on the generated button. ReentryLabel is the name of a label in your script that the button will jump to when clicked, and Parameter will be passed in as a string value called "reentryval".<br />
<br />
Example:<br />
<pre><br />
!script {{<br />
--#reentrant|testing<br />
--=Roll|1d20<br />
--+Roll|[$Roll]<br />
--&String|That was a [$Roll.Raw]!<br />
--~x|array;define;MyArray;Apple;Banana;Orange<br />
--+Try it|[rbutton]Hello!::EXEC_PC_SPELL;9[/rbutton]<br />
--X|<br />
<br />
--:EXEC_PC_SPELL|<br />
--+ReentryVal|[&reentryval]<br />
--+The value of Roll is|[$Roll]<br />
--+Value of String|[&String]<br />
--+Array|[@MyArray(0)]<br />
--X|<br />
}}<br />
</pre><br />
<br />
This script sets up some variables and then displays a button labeled "Hello!". If the user clicks the button, the script will be re-entered starting at the "EXEC_PC_SPELL", which will display the content of the variables from the original execution.<br />
<br />
'''''Note: This section needs to be expanded upon'''''<br />
<br />
== Procedure Libraries ==<br />
<br />
You can now create handouts in your game in Roll 20 with the name format "ScriptCards Library NAME", where name is a name you assign to the library. Library names are case sensitive. It is my hope that the more proficient ScriptCards scripters out there will provide procedure libraries (or procedures that can be included in libraries) for others to use to make their scripting life easier. Be they specific to a game system, or to a type of activity, I think a robust set of libraries that GMs could use to enhance their scripting capabilities would be very valuable to the community. Should such things begin to emerge, I’ll create a portion of the ScriptCards Wiki page to house them.<br />
<br />
To include one or more libraries in a script, use the +++libname+++ directive (does not need a -- line associated with it). Multiple library names can be specified by separating them with semicolons (i.e., +++General;dnd5elib;Colorize+++ would include three libraries (General, dnd5elib, and Colorize).<br />
<br />
Included libraries are separated from the main script code by the automatic inclusion of "--X|" before the first library is appended to the script, and all libraries are loaded at the end of the script before script processing takes place.<br />
<br />
Procedures and labels in libraries can be used just as if they were included in the body of your script. Note that this DOES mean that you could, technically, jump into a library with a direct branch (--^) or direct branch conditional, but I recommend using libraries to store reusable procedures.<br />
The Notes section of the library handout stores the library code, and is written just like any other ScriptCards code except:<br />
<br />
* They cannot use roll queries (?{Some Prompt:}) to get information from the user at execution time.<br />
* They cannot use @{} notation to access character and token information.<br />
<br />
Both of these limitation stem from the fact that Procedure Libraries are not processed by the chat server, which is what handles these items.<br />
<br />
Here is an example of handling damage modifications (resistance, vulnerability, and immunity) in D&D 5E with a library:<br />
<br />
<pre><br />
!script {{<br />
+++dnd5elib+++<br />
--#|Damage Modifiers Test<br />
--#targettoken|@{target|token_id}<br />
-->Lib5E_CheckDamageModifiers|ResistType;fire<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] fire damage<br />
<br />
-->Lib5E_CheckDamageModifiers|ResistType;cold<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] cold damage<br />
<br />
-->Lib5E_CheckDamageModifiers|ResistType;poison<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] poison damage<br />
<br />
-->Lib5E_CheckDamageModifiers|ResistType;acid<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] acid damage<br />
<br />
--X|<br />
}}<br />
</pre><br />
<br />
Library content (In a handout called “ScriptCards Library dnd5elib” NOTE: Paste into Notepad first and then paste into the handout in Roll20 to avoid bringing over HTML formatting from the web site):<br />
<br />
<pre><br />
--/|ScriptCards Library: dnd5elib version 0.0.1<br />
--/|Provides various utility procedures for D&D 5E games<br />
<br />
--/|Lib5E_CheckDamageModifiers handle damage resistance, vulnerability, and immunity. <br />
--/|Pass a string variable to be filled with a string to be appended to a dice roll and the damage type <br />
<br />
--:Lib5E_CheckDamageModifiers|damageVariableName;damageType<br />
--&[%1%]|<br />
--?"[*T:npc_vulnerabilities]" -inc "[%2%]"|>_Lib5E_IsVulnerable;[%1%]<br />
--?"[*T:npc_resistances]" -inc "[%2%]"|>_Lib5E_IsResistant;[%1%]<br />
--?"[*T:npc_immunities]" -inc "[%2%]"|>_Lib5E_IsImmune;[%1%]<br />
--<|<br />
<br />
--:_Lib5E_IsVulnerable| --&[%1%]| * 2 [Vulnerable] --<|<br />
--:_Lib5E_IsResistant| --&[%1%]| \ 2 [Resistant] --<|<br />
--:_Lib5E_IsImmune| --&[%1%]| * 0 [Immune] --<|<br />
</pre><br />
<br />
The idea is that the functions in the library create a string that can be appended to a roll to modify the output based on resistances, so you pass Lib5E_CheckDamageModifiers the name of the string variable you want to use and the damage type. The variable (ResistType in this case) will include either nothing, “* 2 [Vulnerable]”, “\ 2 [Resistant]”, or “* 0 [Immune]” which can be included in a roll assignment (--=) to modify the damage as appropriate. The order here might be important if an NPC is misconfigured to be both resistant and immune to the same damage type. Since immune is an absolute, having it last ensures that it will override resistant or vulnerable. A creature that is both vulnerable and resistant (again, misconfigured) will come back as resistant since that condition is checked after vulnerable.<br />
Some notes: I prefix my library labels with either “Lib5E_” or “_Lib5E_” as a clarity convention. This isn’t strictly necessary but you should be aware that if two libraries (or if your script and a library) define the same label, the last label defined will win. Since libraries are appended to the end of the script in the order you include them in the +++libname+++ directive, you can somewhat control this, but it is probably best to avoid re-declaring labels. <br />
<br />
In my case, items beginning with “Lib5E_” are intended to be called by scripts, while items beginning with “_Lib5E_” are intended to be used as subroutines by the “public” procedures. Of course, there is no reason you couldn’t call them directly.<br />
<br />
You might also note that I’ve included some library information in comment lines (--/|) at the top of the library. These are ignored by ScriptCards, and are a good way to convey requirements, parameters, usage information, etc.<br />
<br />
== Example Libraries ==<br />
<br />
=== dnd5elib ===<br />
<br />
[https://github.com/kjaegers/ScriptCards Download the dnd5elib Library from the ScriptCards GitHub]<br />
<br />
The '''dnd5elib''' library provides a collection of utility procedures that help simplify dealing with the D&D 5E Official Sheet. Some of the procedures in this library require '''chatsetattr''' to be installed in your game. This is a growing library, and currently only has a handful of routines. They are:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Procedure Name !! Notes<br />
|-<br />
| style="white-space:nowrap" | Lib5E_CheckDamageModifiers || This procedure can be used to evaluate vulnerabilities, resistances, and invulnerabilities on an NPC. After setting the --#target| parameters, pass the Lib5E_CheckDamageModifiers procedure a variable name (no reference information) and a damage type (i.e., fire, cold, bludgeoning, etc.) and a string variable with the name passed in as the first parameter will be created that contains text that can be included in a roll line (--=) in order to modify the roll as appropriate. For example, '''-->Lib5E_CheckDamageModifiers|ResistType;fire''' will check the current target character's attributes for "fire" and will either return an empty string (no references), "* 0 [Immune]" if the creature is immune, "\ 2 [Resistant]" if the creature is resistant, or "* 2 [Vulnerable]" if the creature is vulnerable to fire damage.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_DeductSpellSlot || Pass in a character_id and a slot level, and the script will expend one spell slot of that level, capping the value at 0 slots remaining. For Example '''<nowiki>-->Lib5E_DeductSpellSlot|@{selected|character_id};1</nowiki>''' to deduct a first level spell slot from the selected character.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_FindResource || Used to locate a resource value on a character. Pass in a character_id, a resource name, and two variable names. The procedure will check both repeating and non-repeating resources looking for a resource whose name matches what was passed in and return three variables. The first will be a string variable named for the 3rd parameter and contains the attribute name of the resource's "name" field. The second will be a string variable named after parameter 4 and contains the resource's value field attribute name, and the third variable is a Roll Variable, also named after the 4th parameter that contains the current resource value. Example: '''<nowiki>-->Lib5E_FindResource|@{selected|character_id};Crossbow bolts;ResName;ResValue</nowiki>''' will find "Crossbow bolts" as a resource on the character and return [&ResName] which is the name of the resource attribute, [&ResValue] which is the '''name of the attribute that stores the value''' and [$ResValue] which is the current numeric value of the resource.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Global_Attack_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Attack Modifiers (repeating_tohitmod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Bless" for 1d4 active and "Being Cool" for +2 active, I will get a return string " + 1d4 [Bless] + 2 [Being Cool]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Save_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Save Modifiers (repeating_savemod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Bless" for 1d4 active and "Being Cool" for +2 active, I will get a return string " + 1d4 [Bless] + 2 [Being Cool]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Skill_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Skill Modifiers (repeating_skillmod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Guidance" for 1d4 active and "Being Cool" for +2 active, I will get a return string " + 1d4 [Guidance] + 2 [Being Cool]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_AC_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Save Modifiers (repeating_savemod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Shield of Faith" with a value of 2 active, I will get a return string " + 2 [Shield of Faith]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Damage_Modifiers || Pass a character ID and TWO string variable to set the return value. The first string will be for normal damage, and the second will be the additional damage on a crit. This procedure will look through the Global Damage Modifiers (repeating_damagemod_*) for rows that are active (checked on the character sheet) and return two strings with the dice rolls and descriptions for them (for example, if I have "Sneak Attack" with a value of 1d6 normal and 1d6 critical damage active, I will get a return string " + 1d6 [Sneak Attack]" and another string of " + 1d6 [Sneak Attack CRIT]" that can be used in a dice rolls.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_DivineSmiteDice || Used to calculate the number of dice to be rolled for a paladin's Divine Smite. Pass a target token id, a spell slot level, and a string variable to be set to the dice roll amount based on the NPC_TYPE attribute of the target token. The returned variable will contain a dice roll (like "3d8" that can be used in a --= line)<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Character_Summary || Outputs a mini character sheet, including clickable buttons for attacks, actions, legendary actions, etc. Will automatically detect a PC vs NPC and output the appropriate sections.<br />
|}<br />
<br />
Due to formatting issues with the Wiki, the library code has been moved to a [https://gist.github.com/kjaegers/52f6049ddd257f0a1288aca4bbde13c5 GITHUB GIT]. Please view the GIST in raw mode and copy the text and paste it into a handout called "ScriptCards Library dnd5elib" in your Roll20 Game.<br />
<br />
== What to Know if you are Coming from PowerCards ==<br />
<br />
''Note: This section is a work in progress.''<br />
<br />
While ScriptCards and PowerCard have very similar output goals, their internals and use are quite different. The table below summarizes some of the major differences between the scripts.<br />
<br />
::{| class="wikitable"<br />
|-<br />
! PowerCards !! ScriptCards <br />
|-<br />
| With a handful of exceptions, all lines in a PowerCard macro are intended to produce a line of output on the final card. || With ScriptCards, ONLY the <code>--+</code> and <code>--*</code> statement types produces output <br />
|-<br />
| PowerCards lines begin with two dashes (<code>--</code>) followed by a unique tag name for the line, followed by a vertical bar and the content for the line. || ScriptCards lines begin with two dashes (<code>--</code>) followed by a '''statement type identifier''', which is a single character that identifies the type of line to the interpreter. This is followed by a tag (frequently optional), a vertical bar, and the parameters for the statement being executed.<br />
|-<br />
| PowerCard macros are always processed top to bottom. Lines can be hidden so they don't output anything, but there is no looping or branching (--SkipTo looks like a branch, but it just hides all of the lines until the referenced label. || ScriptCards scripts support true branching, including direct branching (<code>--^</code>) and procedure branching (<code>--></code>) and (<code>--<</code>). Procedures support parameters and a call stack so procedures can be nested to call other procedures.<br />
|-<br />
| All lines in a PowerCards macro need to have unique tags because PowerCards builds the card as a single JavaScript object using the tag names to store what will be displayed. This is why repeated tag names always result in the last one being shown. || ScriptCards tags do not need to be unique, and in the case of many line types are optional.<br />
|-<br />
| PowerCards conditionals result in either showing or hiding the line they are on. || ScriptCards conditionals '''''only''''' support branching as the result of the comparison. This branching can be direct (a GOTO) or procedural (a GOSUB) '''''NOTE: As of version 1.2.0, ScriptCards also supports roll/string variable assignment as a result of conditional evaluation'''''<br />
|-<br />
| PowerCards relies on the Roll20 [[Quantum Roll]] server and inline rolls for all dice functions || ScriptCards includes its own dice roll parser, and '''''does not support''''' inline rolls.<br />
|-<br />
| PowerCards RollIDs (often mistaken for variables) are assigned by analyzing the results of an inline roll, and cannot be referenced in other rolls, so you can't roll a <code>1d4</code> and then roll a <code>1d20</code> and add the <code>1d4</code> result because all of the rolls happen on the chat server before PowerCards gets the macro text. || ScriptCards supports two types of variables: Roll Variables and String Variables. Because ScriptCards uses its own roll parser and is not dependent upon the chat server, rolls and their results can be used in other rolls, math functions, output, etc.<br />
|}<br />
<br />
== Example Scripts ==<br />
<br />
Below are some sample scripts that utilize the various statement types in ScriptCards:<br />
<br />
=== Divine Smite ===<br />
<br />
This script will prompt the user for a spell slot level to expend on a divine smite. It will check the target's npc_type to see if it is an Undead or Fiend, which adds an additional d8 to the smite roll.<br />
<br />
[[File:ScriptCards Divine Smite.png|Divine Smite Script Output]]<br />
<br />
<pre><br />
!scriptcard {{<br />
--#title|Divine Smite<br />
--=DiceCount|?{Spell Slot Level?|1|2|3|4|5|6|7|8|9} + 1<br />
--=IsFiendOrUndead|0<br />
--?"@{target|npc_type}" -inc fiend|>IsBoosted<br />
--?"@{target|npc_type}" -inc undead|>IsBoosted<br />
--=TotalDice|[$DiceCount] + [$IsFiendOrUndead]<br />
--=SmiteRoll|[$TotalDice]d8<br />
--#emoteText|@{selected|token_name} smites @{target|token_name}<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
--+Smite|deals [$SmiteRoll] radiant damage.<br />
--X|<br />
<br />
--:IsBoosted|<br />
--=IsFiendOrUndead|1<br />
--<|<br />
}}<br />
</pre><br />
<br />
==== How It Works ====<br />
<br />
The first line sets the "title" card parameter to "Divine Smite".<br />
<br />
Line 2 Shows a query to the user asking for the spell slot level, adds one and stores the value in the "DiceCount" Roll Variable. The query/dropdown is generated by the chat server prior to the script being executed.<br />
<br />
Line 3 defaults the "IsFiendOrUndead" Roll Variable to 0.<br />
<br />
Lines 4 and 5 compare the target's "npc_type" attribute (passed by the chat server as text) to see if they include either "undead" or "fiend". If true, the IsBoosted subroutine will be called. No parameters are passed to this subroutine.<br />
<br />
Line 6 sets the "TotalDice" variable to the base (DiceCount) number plus the IsFiendOrUndead number, which will be a 0 or a 1.<br />
<br />
Line 7 calculates "SmiteRoll" by rolling a number of d8 equal to the "TotalDice" value.<br />
<br />
Lines 8-10 set the parameters for the emote, which appears above the card content. By setting the sourceToken and the targetToken, their icons will appear in the emote surrounding the text describing the action.<br />
<br />
Line 11 is the only line that actually produces output on the card. It results in "Smite deals # radiant damage".<br />
<br />
Line 12 ends the script execution, preventing the script from continuing and running the subroutines out of context.<br />
<br />
Lines 14-16 are the IsBoosted subroutine, starting with the :IsBoosted label. The IsFiendOrUndead variable is set to 1, and a return from subroutine is executed.<br />
<br />
=== Magic Missile ===<br />
<br />
This script demonstrates using a loop and calling a subroutine to fire a number of missiles determine by the spell slot level used to cast the spell.<br />
<br />
[[File:ScriptCards_MagicMissile_Fixed.png|Magic Missile Script Output]]<br />
<br />
<pre><br />
!scriptcard {{ <br />
--#title|Magic Missile<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
--=MissileCount|?{Spell Slot Level?|1|2|3|4|5|6|7|8|9} + 2<br />
--=DisplayCount|1<br />
--=MissileDamage|0<br />
--#leftsub|Slot level ?{Spell Slot Level?}<br />
--#rightsub|Ranged Attack<br />
--#emoteText|Fred uses a level ?{Spell Slot Level?} spell slot to fire [$MissileCount.Total] missiles of magical force!<br />
--:MissileLoop|<br />
-->FireMissile|<br />
--=DisplayCount|[$DisplayCount] + 1<br />
--?[$DisplayCount] -le [$MissileCount]|MissileLoop<br />
--+Total|Total damage is [$MissileDamage]<br />
--X|<br />
<br />
--:FireMissile|<br />
--=ThisMissile|1d4 + 1<br />
--=MissileDamage|[$MissileDamage] + [$ThisMissile]<br />
--+Missile|[$DisplayCount.Total] Hits for [$ThisMissile] [b]force[/b] damage<br />
--<|<br />
}}<br />
</pre><br />
<br />
==== How It Works ====<br />
<br />
Lines 1-3 set the card title, the source token and the target token. Setting these tokens causes their icons/avatars to appear in the Emote section of the card.<br />
<br />
Line 4 asks the user what spell slot level they wish to use to cast magic missile. The number of missiles fired is equal to 2 plus the spell level, and this is stored in the MissileCount variable.<br />
<br />
Line 5 stores a 1 in the DisplayCount variable. This will be used to control the loop to determine the number of missiles fired and the missile number when displaying damage rolls.<br />
<br />
Line 6 initializes MissileDamage to 0<br />
<br />
Line 7 sets the left subtitle to the text "Slot Level #", where # is the spell slot level being used.<br />
<br />
Line 8 sets the right subtitle to the text "Ranged Attack".<br />
<br />
Line 9 sets the emoteText parameter with a description of the action, including the slot level and number of missiles fired.<br />
<br />
Line 10 is a label for the missile firing loop<br />
<br />
Line 11 Calls the "FireMissile" subroutine<br />
<br />
Line 12 increases the DisplayCount variable by 1<br />
<br />
Line 13 Checks to see if there are still missles to fire (DisplayCount <= MissileCount) and if so branches to MissileLoop<br />
<br />
Line 14 Displays the total damage dealt by the spell.<br />
<br />
Line 15 stops execution of the script to prevent out of context execution of the subroutine.<br />
<br />
Lines 76-21 are the FireMissile subroutine, beginning with the FireMissile label. The 1d4+1 is rolled and assigned to "ThisMissile". The result is added to the existing MissileDamage total, and a line for the current missile is displayed with the missile number and the damage for the missile.<br />
<br />
=== Longsword Attack ===<br />
<br />
This script demonstrates a standard 5E D&D melee weapon attack, including detection of misses, fumbles, hits, and critical hits. If installed, alterbars is used to decrement the target's BAR3 value by the damage dealt.<br />
<br />
[[File:ScriptCards Longsword.png|Longsword Script Output]]<br />
<br />
<pre><br />
!scriptcard {{<br />
--#title|Longsword<br />
--#leftsub|Melee Attack<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
--#emoteText|@{selected|token_name} attacks @{target|token_name}<br />
--=TargetAC|@{target|npc_ac}<br />
--?[$TargetAC.Total] -gt 0|DoneWithAC<br />
--=TargetAC|@{target|ac}<br />
--:DoneWithAC|<br />
--=AttackRoll|1d20 + @{selected|strength_mod} [STR] + @{selected|pb} [PROF]<br />
--+Attack|@{selected|token_name} rolls [$AttackRoll] vs AC [$TargetAC].<br />
--?[$AttackRoll.Base] -eq 20|Crit<br />
--?[$AttackRoll.Base] -eq 1|Fumble<br />
--?[$AttackRoll.Total] -ge [$TargetAC.Total]|Hit<br />
--+Miss|The attack missed.<br />
--^Final|<br />
<br />
--:Fumble|<br />
--+Fumble!|The attack went horribly wrong.<br />
--^Final|<br />
<br />
--:Hit|<br />
--=Damage|1d8 + @{selected|strength_mod} [STR]<br />
--+Hit!|The attack hit @{target|token_name} for [$Damage] slashing damage.<br />
--@alter|_target|@{target|token_id} _bar|3 _amount|-[$Damage]<br />
--^Final|<br />
<br />
--:Crit|<br />
--=Damage|1d8 + @{selected|strength_mod} [STR] + 1d8 [CRIT]<br />
--+Critical Hit!|The attack hit @{target|token_name} for [$Damage] slashing damage.<br />
--@alter|_target|@{target|token_id} _bar|3 _amount|-[$Damage]<br />
<br />
--:Final|<br />
}}<br />
</pre><br />
<br />
==== How it Works ====<br />
<br />
In lines 1-5, we set the title, subtitle, and emote text along with the tokens for the emote area.<br />
<br />
Lines 6-9 allow us to determine the AC of the target. On the 5E Roll20 sheet, NPCs armor class is stored in "npc_ac", while PCs armor class is in "ac". First we grab npc_ac and if it is zero, we check AC.<br />
<br />
Line 10 rolls the attack roll, rolling 1d20 and adding the attacker's strength modifier and proficiency bonus<br />
<br />
Line 11 displays the result of the attack roll on the card<br />
<br />
Lines 12-14 determine what kind of result the attack had. If the .Base value of the roll was 20, we branch to "Crit". If it was 1, we branch to "Fumble". If the .Total value of the roll was greater than or equal to the AC that was determined in Lines 6-9, we branch to Hit.<br />
<br />
Assuming we didn't branc anywhere, the result of the attack was a miss, so we display that on line 15 and then branch to "Final"<br />
<br />
This is followed by three branch segments, :Fumble, :Hit, and :Crit. A fumble displays a text message and branches to :Final.<br />
<br />
On a hit or a crit, we roll Damage (adding additional damage dice on a crit). We display a "Hit!" or "Critical Hit!" message and then make an API call to AlterBars, passing it the token id, bar we want to modify (3 in this case), and the amount we want to modify by the Damage value.<br />
<br />
=== Party Health Status ===<br />
<br />
This example calculates the current Hit Points remaining and HP percentage for each character and creates a color-coded display with the current party status.<br />
<br />
[[File:ScriptCards Party Health.png]]<br />
<br />
<pre><br />
!scriptcard {{<br />
--#title|Party Status<br />
--#titleCardBackground|#33CC33<br />
--#oddrowbackground|#bfee90<br />
--#evenrowbackground|#90eebf<br />
-->HealthCheck|@{Quej Grastra|character_id}<br />
-->HealthCheck|@{Brim Cheuto|character_id}<br />
-->HealthCheck|@{Odug Ututees|character_id}<br />
--X|End of card Execution<br />
<br />
--:HealthCheck|<br />
--=HealthPerc|[*[%1%]:hp] / [*[%1%]:hp^] * 100 \ 1<br />
--=HealthColor|000000<br />
--?[$HealthPerc.Total] -gt 50|HealthSkip<br />
--=HealthColor|FF0000<br />
--:HealthSkip|<br />
--+[*[%1%]:character_name]|has [#[$HealthColor.RollText]][*[%1%]:hp] of [*[%1%]:hp^][/#] HP [R]([$HealthPerc.Total]%)[/R]<br />
--<|End of HealthCheck<br />
}}<br />
</pre><br />
<br />
==== How it Works ====<br />
<br />
Lines 1-4, we set the card title, and set the title background and row background colors to shades of green.<br />
<br />
Lines 5-7 make gosub calls the the "HealthCheck" subroutine, passing in the character ID of each of the named characters (these are the names of the characters in my test game)<br />
<br />
Line 8 terminates the script execution.<br />
<br />
The remaining lines of the script are the HealthCheck subroutine, which works like this:<br />
<br />
Line 10 is the subroutine label (:HealthCheck)<br />
<br />
Line 11 uses the character id passed as a parameter and combines it with character attribute lookup *(...) to retrieve the value of "hp" and "hp<nowiki>^</nowiki>" for the character. The <nowiki>^</nowiki> character is used to specify that we want the MAX value for this attribute for the second call. We divide these two numbers and multiple by 100 to get a percentage. Finally, we use integer division by 1 to round the percentage and drop the decimals. The end result gets stored in the HealthPerc roll variable.<br />
<br />
Line 12 defaults to color of the health text to black<br />
<br />
Line 13 check to see if the health percentage is greater than 50. If so, it branches to HealthSkip, preventing the script from executing line 13.<br />
<br />
Line 14 sets the color of the health text to red<br />
<br />
Line 15 is the label that will be branched to from Line 13 to skip the red coloring<br />
<br />
Line 16 again uses character attribute substitution and the passed parameter value to output a display line containing the character name, the colorized health total, and the percentage value. The percentage is right-justified.<br />
<br />
Line 17 returns from the HealthCheck subroutine.<br />
<br />
=== Expanded Magic Missile Script ===<br />
<br />
This is the expanded and enhanced version of the Magic Missile script covered in {{yt|watch?v=u50xvNzS9Zk | this video}}. It includes visual and audio effects, checking and deducting spell slots, and applying damage using either Token-Mod or Alterbars.<br />
<br />
<pre><br />
!scriptcard {{ <br />
--#title|Magic Missile<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
<br />
-->GetAndCheckSlotInformation|<br />
<br />
--=MissileCount|[$SlotLevel] + 2<br />
--=DisplayCount|1<br />
--=MissileDamage|0<br />
--#leftsub|Slot level [$SlotLevel]<br />
--#rightsub|Ranged Attack<br />
--#emoteText|@{selected|character_name} uses a level [$SlotLevel.Total] spell slot to fire [$MissileCount.Total] missiles of magical force!<br />
<br />
--:MissileLoop|<br />
-->FireMissile|<br />
--=DisplayCount|[$DisplayCount] + 1<br />
--?[$DisplayCount] -le [$MissileCount]|MissileLoop<br />
--+Total|Total damage is [$MissileDamage]<br />
-->DeductSpellSlot|<br />
--#rightsub|Level [$SlotLevel] Left: [$SlotsRemaining] <br />
-->PlayEffects|none;burst-smoke;beam-magic;spell_01<br />
-->ApplyDamageTokenmod|@{target|token_id};3;-[$MissileDamage]<br />
-->ApplyDamageAlterbars|@{target|token_id};3;-[$MissileDamage]<br />
--X|<br />
<br />
--:FireMissile|<br />
--=ThisMissile|1d4 + 1<br />
--=MissileDamage|[$MissileDamage] + [$ThisMissile]<br />
--+Missile|[$DisplayCount.Total] Hits for [$ThisMissile] [b]force[/b] damage<br />
--<|<br />
<br />
--:GetAndCheckSlotInformation|<br />
--=SlotLevel|?{Spell Slot Level?|1|2|3|4|5|6|7|8|9}<br />
--=SlotsTotal|[*S:lvl[$SlotLevel]_slots_total]<br />
--=SlotsExpended|[*S:lvl[$SlotLevel]_slots_expended]<br />
--?[$SlotsExpended.Total] -ge [$SlotsTotal.Total]|NoSlotsLeft<br />
--<|<br />
<br />
--:NoSlotsLeft|<br />
--+|[*S:character_name] has no level [$SlotLevel.Total] spell slots available.<br />
--X|<br />
<br />
--:DeductSpellSlot|<br />
--=SlotsExpended|[$SlotsExpended] + 1<br />
--@setattr|_charid [*S:character_id] _lvl[$SlotLevel]_slots_expended|[$SlotsExpended] _silent<br />
--=SlotsRemaining|[$SlotsTotal] - [$SlotsExpended]<br />
--<|<br />
<br />
--:PlayEffects|Parameters are : source effect; target effect; line effect; sound effect<br />
--vtoken|@{selected|token_id} [%1%]<br />
--vtoken|@{target|token_id} [%2%]<br />
--vbetweentokens|@{selected|token_id} @{target|token_id} [%3%]<br />
--@roll20AM|_audio,play,nomenu|[%4%]<br />
--<|<br />
<br />
--:ApplyDamageTokenmod|Parameters are tokenid;bar#;amount<br />
--@token-mod|_ignore-selected _ids [%1%] _set bar[%2%]_value|[%3%]<br />
--<|<br />
<br />
--:ApplyDamageAlterbars|<br />
--@alter|_target|[%1%] _bar|[%2%] _amount|[%3%]<br />
--<|<br />
}}<br />
</pre><br />
<br />
[[Category:Featured articles]]</div>5004103https://wiki.roll20.net/Script:ScriptCardsScript:ScriptCards2021-09-27T13:04:03Z<p>5004103: /* Character/Token Attributes */</p>
<hr />
<div>{{revdate}}<br />
== Introduction ==<br />
'''ScriptCards''' provides a script interpreter that can be used to create powerful macros that display the results of player/NPC actions, or display other information in a pleasing visual format in your game's chat window. The scripting language contains variables (both dice-roll (enhanced numerics) and strings) as well, conditionals, branching, subroutines with parameters, and a set of built-in functions to simplify working with Roll20 information.<br />
{{script overview<br />
|name=ScriptCards<br />
|author={{user profile|2365448|Kurt J.}}<br />
|code=<br />
|version=1.4.0e<br />
|lastmodified=2021-09-24}}<br />
ScriptCards is not game-system specific, and can be used with any system/sheet. Near the end of this Wiki there is a section set aside for libraries that can implement system-specific tasks, with the hope that enthusiasts playing particular systems will create and share utility functions that can be utilized by the wider community.<br />
<br />
The default display style for ScriptCards output is similar to the format used to document player and NPC abilities in Dungeons and Dragons 4th Edition, but does not have any system ties to D&D4E.<br />
<br />
Current OneClick Version : 1.4.0e<br />
<br />
Current Development Version : 1.4.4<br />
<br />
'''''<big>Critically Important: ScriptCards does not use/parse inline rolls. ScriptCards includes its own built-in dice roll parser to allow for the use of variables inside dice rolls. As of version 1.2.3, ScriptCards will now take inline rolls and substitute the total result value in statement strings, meaning that you can utilize inline rolls but ScriptCards will only see the result of the roll, and not parse the roll components itself.</big>'''''<br />
<br />
* {{fpl|9752053/ ScriptCards thread}}<br />
** {{fpl|10000297/ Scritpcard API Working and Sharing}}<br />
* https://github.com/kjaegers/ScriptCards/tree/main/ScriptCards_API - GitHub repository for source before the one-click version is updated.<br />
* {{yt.be|hyR7Jnq4mQM ScriptCards Intro}} 45min, Jan 2021<br />
* {{yt.be|u50xvNzS9Zk ScriptCards Magic Missile Deep Dive}} 39min, Feb 2021<br />
<br />
<br />
__TOC__<br />
=== Is ScriptCards Related to [[PowerCards]]? ===<br />
<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
Check the '''[[#What to Know if you are Coming from PowerCards|What to Know if you are Coming from PowerCards]]'''-section for a comparison table between the two scripts.<br />
<br />
== What is a ScriptCard Script ==<br />
<br />
A ScriptCard Script is text written into the chat window (either typed directly, pasted, or run via a macro) that will produce a card of information in the [[text Chat|chat window]]. A ScriptCard Script is composed of an [[API]] command: <code><nowiki>!scriptcard {{ }}</nowiki></code> enclosing any number of lines that determine the output that will be added to the card. At it simplest, the following macro:<br />
<br />
<pre>!scriptcard {{ }}</pre><br />
<br />
Will produce just a title card that displays “ScriptCards” as the name:<br />
<br />
[[File:Scriptcard blank.png]]<br />
<br />
Of course, this is just the simplest type of macro and isn’t very useful. In order to produce useful output, we need to include lines between the <code><nowiki>{{</nowiki></code> and <code><nowiki>}}</nowiki></code> that direct the API script as to what it should do.<br />
<br />
== Structure of a ScriptCard Line ==<br />
<br />
All ScriptCard lines begin with two dashes, followed by an ''statement identifier character'' that lets ScriptCards what type of line it is. There are several of these, and they are detailed in the next section. After the line type identifier, a Tag name 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.<br />
<br />
Following the Tag is a vertical bar, and then the content of the line itself. Again, each type of line might interpret this content differently.<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Identifier !! Statement Type !! Tag !! Content !! Notes<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--/</nowiki> || Comment || unused || unused || The <code>--/</code> 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--#</nowiki> || 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").<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--+</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--=</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--&</nowiki> || Assign String 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. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--@</nowiki> || 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 (i.e., [[TokenMod|!token-mod]], or [[ChatSetAttr|!setattr]], etc.)<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--:</nowiki> || 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<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--^</nowiki> || Branch To || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--></nowiki> || Call Procedure || 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<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--<</nowiki> || 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.<br />
|- <br />
| style="white-space:nowrap" | <nowiki>--?</nowiki> || Conditional Branch || Condition to be evaluated || True Branch Label<nowiki>|</nowiki>False Branch Label || The condition will be evaluated and execution will jump to one of the two indicated branches (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 included a semicolon separated list of parameters. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--s</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--l</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--v</nowiki> || 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+'''''<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--e</nowiki> || Echo to Chat || Name to send chat command as || Chat message to send || Variable substitution takes place on the tag and content.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--R</nowiki> || Retrieve Repeating Section Row information || "find", "first", or "next" || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--~</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--c</nowiki> || 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.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--i</nowiki> || Information Request || User Prompt;Button Caption || InfoType;VariableName;ParameterText || See full documentation below.<br />
|-<br />
| style="white-space:nowrap" | <nowiki>--d</nowiki> || 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. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--%</nowiki> || 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. <br />
|-<br />
| style="white-space:nowrap" | <nowiki>--*</nowiki> || 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.<br />
|}<br />
<br />
== ScriptCard Statement Type Details ==<br />
The sections below detail the individual statement types supported by ScriptCards<br />
<br />
=== Comment (--/) ===<br />
<br />
A --/ statement is ignored by the ScriptCards parser. You can use this type of statement to add comments and informational text to your script. <br />
<br />
Example:<br />
<pre><br />
!script {{<br />
--/|Script Name : Fireball<br />
--/|Purpose : Allow the player to cast a fireball and blow stuff up!<br />
.<br />
.<br />
.<br />
}}<br />
</pre><br />
<br />
=== Set Parameter (--#) ===<br />
<br />
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.<br />
<br />
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.<br />
<br />
'''''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.'''''<br />
<br />
Examples:<br />
<pre><br />
--#title|Magic Missile<br />
--#leftsub|Level 1 Spell<br />
--#rightsub|Force Damage<br />
</pre><br />
<br />
The three examples above set the “title”, “leftsub”, and “rightsub” values for the card to the content value for the line. <br />
<br />
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.<br />
Settings Lines do not produce output lines on the card.<br />
<br />
The following settings are available (note that parameter names are ''not'' case sensitive):<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Name !! Effect/Use !! Default Value !! Type<br />
|-<br />
| 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<br />
|-<br />
| allowplaintextinrolls || If set to a non-zero value, plain character text in rolls will be copied to the roll text || 0 || Per-Line<br />
|-<br />
| bodyFontFace || Name of the font used in the card rows || Helvetica || Global<br />
|-<br />
| bodyFontSize || Size of the text in the card rows || 14px || Global<br />
|-<br />
| bodybackgroundimage || Specify an image (content for a CSS background-image tag) for the body area || none || Global<br />
|-<br />
| buttonBackground || Background color for buttons created with [button][/button] || #1C6EA4 || Per-Line<br />
|-<br />
| buttonBorderColor || Border (outline) color for buttons created with [button][/button] || #999999 || Per-Line<br />
|-<br />
| buttonFontFace || Font Family specifier for captions on buttons created with [button][/button] || Tahoma || Per-Line<br />
|-<br />
| buttonFontSize|| Text size for captions on buttons created with [button][/button] || x-small || Per-Line<br />
|-<br />
| buttonTextColor|| Text color of labels on buttons created with [button][/button] || #FFFFFF || Per-Line<br />
|-<br />
| 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<br />
|-<br />
| deferralcharacter || Changes the meta script deferral sequence to the specified value || ^ || Per-Line<br />
|-<br />
| diceFontColor|| Color of the dice created with the [d4] [d6], etc. formatting markers || #1C6EA4 || Per-Line<br />
|-<br />
| dicefontsize || Size of the dice created with the [d4] [d6], etc. formatting markers || 3.0em || Per-Line<br />
|-<br />
| 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<br />
|-<br />
| disablerollprocessing || If set to a non-zero value, --= lines will not process dice rolls strings || 0 || Per-Line<br />
|-<br />
| emoteBackground || Background color of the emote area || #f5f5ba || Global<br />
|-<br />
| emoteFont || Name of the font used in emote area (above the title of the output card) || Georgia || Global<br />
|-<br />
| emoteFontColor || Color of the font in the emote area || None (Empty) || Global<br />
|-<br />
| emoteFontSize || Size of the font used in the emote area || 14px || Global<br />
|-<br />
| emoteFontWeight || Font weight for the font in the emote area || bold|| Global<br />
|-<br />
| emoteState || If set to anything other than "visible", the emote portion of the card will not be displayed || visible || Global<br />
|-<br />
| emoteText || Text to display in the emote portion of the card || None (Empty) || Global<br />
|-<br />
| emotefont || Name of the font used in the emote text area || font-family: Georgia, serif; font-weight: bold; || Global<br />
|-<br />
| evenRowBackground || Hex code for the background color for even rows || #eeeeee || Per-Line<br />
|-<br />
| evenRowFontColor || Hex code for the text color for even rows || #000000 || Per-Line<br />
|-<br />
| evenrowbackgroundimage || Specify an image (content for a CSS background-image tag) for the even card rows || none || Per-Line<br />
|-<br />
| executionlimit || Maximum number of script lines the interpreter will try to execute. This prevents "infinite loop" sandbox crashes || 40000 || Global<br />
|-<br />
| hideCard || If set to any non-default value, the entire card output will be suppressed || 0 || Global<br />
|-<br />
| 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<br />
|-<br />
| 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<br />
|-<br />
| lineheight || Vertical size of each line on the output card || normal || Per-Line<br />
|-<br />
| nominmaxhighlight || If set to anything other than "0", rolls will not display crit/fumble/mixed highlight colors. || 0 || Per-Line<br />
|-<br />
| norollhighlight || If set to anything other than "0", rolls will not be formatted (plain numbers) but will still get a tooltip with details ('''''v1.3.6b+''''') || 0 || Per-Line<br />
|-<br />
| oddRowBackground || Hex code for the background color for even rows || #d0e4f5 || Per-Line <br />
|-<br />
| oddRowFontColor || Hex code for the text color for odd rows || #000000 || Per-Line<br />
|-<br />
| oddrowbackgroundimage || Specify an image (content for a CSS background-image tag) for the odd crd rows || none || Per-Line<br />
|-<br />
| reentrant || Used to name a script for rentrant button use || 0 || Global<br />
|-<br />
| 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)0 || Global<br />
|-<br />
| rollhilightlineheight || Determines the height of the hilight box placed around roll results ('''''1.4.2+''''') || 1.0em || Per-Line<br />
|-<br />
| roundUp || If set to a non-default value, integer division will round up instead of down || 0 || Per-Line<br />
|-<br />
| showfromfornonwhispers || If set to a non-zero value, will include the sender on cards that aren't whispered || 0 || Global<br />
|-<br />
| 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<br />
|-<br />
| subtitleFontColor || Color of the text in the subtitle areas || #FFFFFF || Global<br />
|-<br />
| subtitleFontFace || Name of the font used on the subtitle sections || Tahoma || Global<br />
|-<br />
| subtitleFontSize || Size of the subtitle font || 13px || Global<br />
|-<br />
| subtitleSeperator || The character(s) that will be placed between leftsub and rightsub || <nowiki>&#x2666</nowiki>; || Global<br />
|-<br />
| tableBorderRadius || CSS specifier for how rounded the borders of the output card are. Use "0px;" for square borders || 6px; || Global<br />
|-<br />
| tableShadow || CSS specifier for the drop shadow under the output card || 5px 3px 3px 0px #aaa; || Global<br />
|-<br />
| tablebgcolor || Background color of the whole card. '''''Normally not visible''''' || #EEEEEE || Global<br />
|-<br />
| tableborder || Color of the border that surrounds the whole card || 2px solid #000000; || Global<br />
|-<br />
| 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<br />
|-<br />
| timezone || IANA Specifier for the local time zone, used in system/date functions || merica/New_York || Per-Line<br />
|-<br />
| title || Text displayed in the title area of the card || ScriptCards || Global<br />
|-<br />
| titleCardBackground || A hex color code representing the background color of the title area. || #1c6ea4 || Global<br />
|-<br />
| titleFontColor || Color of the text on the card title || #FFFFFF || Global<br />
|-<br />
| titleFontFace || Name of the font used on the title area || Contrail One || Global<br />
|-<br />
| titleFontLineHeight || Line spacing on the title area || 1.2em || Global<br />
|-<br />
| titleFontSize || Size of the title font || 1.2em || Global<br />
|-<br />
| titlecardbackgroundimage || Specify an image (content for a CSS background-image tag) for the title card area || none || Global<br />
|-<br />
| titlecardbottomborder || Border CSS specifier for the bottom of the title card area || 2px solid #444444; || Global<br />
|-<br />
| titlecardgradient || If set to non-zero value, will place a vertical gradient on the title card area || 0 || Global<br />
|-<br />
| usehollowdice || If set to a non-zero value, the hollow/outline versions of the dice fonts will be used || 0 || Per-Line<br />
|-<br />
| whisper|| Comma separated list of who to whisper the output to. Use "gm" for [[GM|GMs]] and "self" for the sender || none || Global|}<br />
|}<br />
<br />
''Setting Lines do not produce output lines on the card''<br />
<br />
=== Direct Output (--+) ===<br />
<br />
A direct output line display 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.<br />
<br />
Examples of Direct Output lines:<br />
<pre><br />
--+Hello|World<br />
--+Attack|The monster rolls [$Attack] to hit!<br />
--+Damage|@{target|token_name} is hit for [$Damage] [#3333AA][b]frost[/b][/#] damage.<br />
</pre><br />
<br />
Direct Output lines support inline formatting, roll variable replacement, character attribute references, and procedure variables.<br />
<br />
=== GM Output (--*) ===<br />
<br />
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. <br />
<br />
Example:<br />
<pre><br />
--+PlayerLine|This line is shown on the public card<br />
--*GMLine|This line will only be shown to GMs, on a separate card.<br />
</pre><br />
<br />
=== Roll Variable Assignment (--=) ===<br />
<br />
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.<br />
<br />
'''''All components of a roll equation should be separated with spaces.'''''<br />
<br />
Examples:<br />
<pre><br />
--=MissileDamage|1d4 + 1<br />
--=Attack|1d20 + @{selected|strength_mod} [STR] + @{selected|pb} [PROF]<br />
</pre><br />
<br />
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. Text enclosed in square brackets ([]) is considered "flavor text" and will be added to the result text but does not impact the roll result.<br />
<br />
The following dice formats are supported:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Format Pattern !! Example !! Description<br />
|-<br />
| XdY || 3d8 || Simple format. Roll a Y-sided die X times<br />
|-<br />
| XdYkhZ || 2d20kh1 || Roll Y-sided die X times and keep the highest Z number of dice<br />
|-<br />
| XdYklZ || 4d6kl3 || Roll Y-sided die X times and keep the lowest Z number of dice <br />
|-<br />
| XdY>Z || 5d6>3 || Roll Y-sided die X times and count a 1 for each roll greater than Z <br />
|-<br />
| XdY<Z || 5d6<3 || Roll Y-sided die X times and count a 1 for each roll less than Z <br />
|}<br />
<br />
'''''Note: The dice formulae below are supported in the development version of ScriptCards and will be merged with the table above when activated on OneClick'''''<br />
::{| class="wikitable"<br />
|-<br />
! Format Pattern !! Example !! Description<br />
|-<br />
| 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<br />
|-<br />
| 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<br />
|-<br />
| 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)<br />
|-<br />
| 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<br />
|}<br />
<br />
The following operators are supported in a roll equation:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Operator !! Operation<br />
|-<br />
| + || Addition <br />
|-<br />
| - || Subtraction <br />
|-<br />
| * || Multiplication <br />
|-<br />
| / || Division <br />
|-<br />
| \ || Integer Division (Rounds down) <br />
|-<br />
| % || Modulo (Remainder of Divison)<br />
|}<br />
<br />
Roll Variables can be accessed at any time after they have been created by using the [$VariableName] format, with the following optional modifiers:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Modifier !! Meaning<br />
|-<br />
| No modifier || In a Direct Output Line (<nowiki>--+</nowiki>) 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<br />
|-<br />
| .Total || The end result of the roll equation as an unformatted number <br />
|-<br />
| .Base || The cumulative result of any dice rolled in the Roll Text (Numeric modifiers are not included) <br />
|-<br />
| .Ones || The number of dice in the roll that came up as 1s <br />
|-<br />
| .Aces || The number of dice in the roll that came up as the maximum number on the die <br />
|-<br />
| .Odds || The number of dice in the roll that came up with an odd number <br />
|-<br />
| .Evens || The number of dice in the roll that came up with an even number <br />
|-<br />
| .RollText || The raw text of the roll that was use to generate the results <br />
|-<br />
| .Text || A text representation of the results of the roll, including the numbers rolled for each die <br />
|-<br />
| .tableEntryText || The text portion of the result of a table roll<br />
|-<br />
| .tableEntryImgURL || The image source portion of the result of a table roll<br />
|-<br />
| .tableEntryValue || Numeric value of tableEntryText (via parseInt). If a non-numeric value, will be 0<br />
|-<br />
| .Raw || The total numeric result without any formatting, even if placed somewhere formatting would normally be done. <br />
|}<br />
<br />
Examples:<br />
<pre><br />
--+Total Damage|[$MissileDamage.Total] (roll was 1d4+1)<br />
--+Base Damage|[$MissileDamage.Base] (without the +1)<br />
--=Attack|1d20 + @{selected|strength_mod} [STR] + @{selected|pb} [PROF] + [$BlessBonus] [Bless]<br />
</pre><br />
<br />
In this case, 1d4 will be rolled and stored in “BlessBonus”, which can then be used in the Attack line.<br />
<br />
'''''Mathematical Functions in Roll Expressions '''''<br />
<br />
The ScriptCards roll parser works from left to right, always maintaining a current value and applying whatever comes next to the total. The following in-line functions to the roll parser. These are:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Expression !! Meaning<br />
|-<br />
| {ABS} || Absolute Value<br />
|-<br />
| {CEIL} || Ceiling value (round up to the next whole number)<br />
|-<br />
| {FLOOR} || Floor value (round down to the next whole number)<br />
|-<br />
| {ROUND} || Round value (round up if the decimal portion is greater than 0.5, otherwise round down)<br />
|-<br />
| {NEGATE} || Multiply the value by negative one.<br />
|-<br />
| {SQRT} || Take the square root of the running value. ('''''1.4.1+''''')<br />
|-<br />
| {SQUARE} || Square the running value. ('''''1.4.2+''''')<br />
|-<br />
| {CUBEROOT} || Take the cube root of the running value. ('''''1.4.2+''''')<br />
|-<br />
| {CUBE} || Cube the running value. ('''''1.4.2+''''')<br />
|-<br />
| {SIN} || Return the SIN of running value. ('''''1.4.2+''''')<br />
|-<br />
| {COS} || Return the COS of running value. ('''''1.4.2+''''')<br />
|-<br />
| {TAN} || Return the TAN of running value. ('''''1.4.2+''''')<br />
|-<br />
| {ASIN} || Return the ASIN of running value. ('''''1.4.2+''''')<br />
|-<br />
| {ACOS} || Return the ACOS of running value. ('''''1.4.2+''''')<br />
|-<br />
| {ATAN} || Return the ATAN of running value. ('''''1.4.2+''''')<br />
|}<br />
<br />
<br />
'''''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 <nowiki>[[ ]]</nowiki> 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.<br />
<br />
'''''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.<br />
<br />
'''Rolling on Rollable Tables'''<br />
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.<br />
<br />
''Roll Variable Lines do not produce output lines on the card.''<br />
<br />
=== String Variable Assignment (--&) ===<br />
<br />
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:<br />
<br />
<pre><br />
--&MyText|Hello<br />
</pre><br />
<br />
Here, we assign the text "Hello" to the string variable named MyText. You can also append text to a string variable by prefixing the content with a + sign:<br />
<br />
<pre><br />
--&MyText|+ World<br />
</pre><br />
<br />
If run after the statement above, MyText will now contain "Hello World".<br />
<br />
String variables can be referenced using the syntax [&variablename]<br />
<br />
=== Call API (--@) ===<br />
<br />
ScriptCards can use a Call API instruction to execute other API commands. The Tag contains the API 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 API command is executed.<br />
<br />
Examples:<br />
<pre><br />
--@eh|list<br />
--@alter|_target|@{target|token_id} _bar|3 _amount|-[$Damage]<br />
</pre><br />
<br />
In the first example above, the command <code>!eh list</code> will be executed, calling [[EncounterHelper]]. In the second, {{fpl|1216260/ AlterBars}} is called to modify a token's Bar 3 value.<br />
<br />
'''''Note:''''' When ScriptCards (or any API script) runs other API 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).<br />
<br />
See [[API:Script Index]] for more options.<br />
<br />
=== Branch Label (--:) ===<br />
<br />
A branch label defines a line in your code that can be reached by one of the branching instructions (<nowiki>--^</nowiki>, <nowiki>--></nowiki>, or <nowiki>--?</nowiki>). The Tag serves as the label name, and must be unique on the card.<br />
<br />
The vertical bar (|) separator must be present, but the content portion of the line is unused and can be treated as a comment.<br />
<br />
Examples:<br />
<pre><br />
--:MyLoop|<br />
--:CriticalHit|Will jump here if we roll a critical hit!<br />
</pre><br />
<br />
''A Branch Label line does not produce an output line on the card.''<br />
<br />
=== Branch (--^) === <br />
<br />
A Branch line 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.<br />
<br />
Examples:<br />
<pre><br />
--^MyLoop|Jumps to MyLoop<br />
--^SkipCrit|We didn't crit, so skip the Crit code<br />
</pre><br />
<br />
''A Branch line does not produce an output line on the card.''<br />
<br />
=== Call Procedure (-->) ===<br />
<br />
Similar to a branch, a Call Procedure (sometimes knows 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 (<nowiki>--<</nowiki>) 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 (;).<br />
<br />
Examples:<br />
<pre><br />
-->FixFormat|#3333FF;#999999<br />
</pre><br />
<br />
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%].<br />
<br />
=== Return (--<) ===<br />
<br />
A return instruction marks the end of a Gosub procedure. 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.<br />
<br />
Examples:<br />
<pre><br />
--<|<br />
--<|End of MySub<br />
</pre><br />
<br />
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.<br />
<br />
=== Conditional Statement (--?) ===<br />
<br />
A conditional statement contains some equation in the Tag that will be evaluated. '''''If any part of the comparison can/does contain a space, it needs to be surrounded by double quotes'''''<br />
<br />
Based on the true/false result of the evaluation, one of two execution paths will be taken. These execution paths are detailed in the content section of the statement. The "if true" path is specified first (directly after the vertical bar), and the "if false" path is specified after it, also separated by a vertical bar.<br />
<br />
Example:<br />
<pre><br />
--?[$AttackRoll.Total] -ge [$TargetAC]|Hit|Miss<br />
</pre><br />
<br />
'''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.'''<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Branch Format !! Meaning<br />
|-<br />
| Label || If just a label is specified, execution will branch to that label when the comparison is matched.<br />
|-<br />
| >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 <br />
|-<br />
| =VariableName || The roll variable "VariableName" will be assigned the value following a semicolon (ex: --?1 -eq 1|=Roll;1d20)<br />
|-<br />
| &VariableName || The string variable "VariableName" will be assigned the value following a semicolon (ex: --?1 -eq 1|&Result;Hit|&Result;Miss)<br />
|-<br />
| % or %! || The current for...next loop will perform the "next" action (%) or will break out (%!) <br />
|-<br />
| [ || Code block (see below)<br />
|}<br />
<br />
Examples:<br />
<pre><br />
--?[$AttackRoll.Base] -eq 20|CriticalHit<br />
--?[$AttackRoll.Base] -eq 1|>Fumble;@{selected|dexterity_mod}<br />
--?"@{target|npc_type}" -inc "undead"|&MonsterType;Undead|&MonsterType;Not Undead<br />
--?[$Attack.Total] >= [$ArmorClass]|>Hit|>Miss<br />
</pre><br />
<br />
In the first example, if the Base value of AttackRoll is a 20 (natural 20 on the die) execution will branch to the CriticalHit label.<br />
<br />
In the second example, 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%].<br />
<br />
The third example looks for the word "undead" in the npc_type attribute of the targeted character. If it exists in the text, the MonsterType string variable will be set to "Undead", otherwise it will be set to "Not Undead". <br />
<br />
The final example would call 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.<br />
<br />
''Text that does/may contain a space should be enclosed in double quotes.''<br />
<br />
The following comparison operators are available:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Comparator !! Meaning<br />
|-<br />
| -eq || Equal To <br />
|-<br />
| -eqi || Case insensitive Equal To <br />
|-<br />
| -ne || Not Equal To <br />
|-<br />
| -nei || Case insensitive Not Equal To <br />
|-<br />
| -gt || Greater Than <br />
|-<br />
| -ge || Greater Than or Equal To <br />
|-<br />
| -lt || Less Than <br />
|-<br />
| -le || Less Than or Equal To <br />
|-<br />
| -inc || Includes (text strings). <br />
|-<br />
| -ninc || Does Not Include (text strings). <br />
|}<br />
<br />
Multi-part conditionals are supported with -and and -or as separators. For example:<br />
<br />
<pre><br />
--?[$Attack.Total] -ge @{target|npc_ac} -and [$Attack.Base] -ne 20|HitButNotCrit<br />
</pre><br />
<br />
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):<br />
<br />
true AND false OR true<br />
<br />
Will be evaluated as true. The first two (true and false) will be false, but then false OR true will be true.<br />
<br />
Conversely:<br />
<br />
true or false and false<br />
<br />
Will be false, because the first true and false will evaluate to true, and then true and false will be false.<br />
<br />
'''CODE BLOCKS'''<br />
<br />
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.<br />
<br />
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:<br />
<br />
<pre><br />
!script {{<br />
--=Roll|1d2<br />
--+Roll|[$Roll]<br />
--?[$Roll.Total] -eq 2|[<br />
--&Value|Yep!<br />
--+|We are inside the TRUE portion of the block<br />
--]|[<br />
--&Value|Nope<br />
--+|We are inside the FALSE portion of the block<br />
--]|<br />
--+After|the blocks!<br />
--+Value|[&Value]<br />
}}<br />
</pre><br />
<br />
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 --]|. <br />
<br />
At this time, blocks cannot be nested, and can only be created as part of a conditional (--[ is not a valid statement type)<br />
<br />
''A conditional statement does not produce a line of output on the card.''<br />
<br />
=== Case Statement (--c) ===<br />
<br />
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 (:). Each match condition includes a branch label that will be used if the test value matches the item. 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:<br />
<br />
<pre><br />
!script {{<br />
--#title|Case Statement Testing<br />
--=Roll|1d4<br />
--C[$Roll.Total]|1:>One;[$Roll]|2:>Two;[$Roll]|3:>Three;[$Roll]|4:>Four;[$Roll]<br />
--X|<br />
<br />
--:One| --+Value|was One ([%1%]) --<|<br />
--:Two| --+Value|was Two ([%1%]) --<|<br />
--:Three| --+Value|was Three ([%1%]) --<|<br />
--:Four| --+Value|was Four ([%1%]) --<|<br />
}}<br />
</pre><br />
<br />
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 variable as a parameter.<br />
<br />
=== Save and Load (--s and --l) ===<br />
<br />
This statement pair is used to either store (--s) or load (--l) data from persistent storage. Items stored in persistent storage remain between card rolls and between Roll20 sessions. There are two types of data that can be stored: settings and roll variables. <br />
<br />
Examples:<br />
<br />
<pre><br />
--Ssettings|GreenStyle<br />
--Srollvariables|FirstCardVars<br />
</pre><br />
<br />
In this case, the tag for the statement determines what type of item is being saved (settings or rollvariables). When saving settings, all non-default settings are written to the named setting storage value. When Roll Variables are saved, all variables that currently exist will be saved to the named storage value.<br />
<br />
Loading stored items simply requires the same command with the --l statement type:<br />
<br />
<pre><br />
--Lsettings|GreenStyle<br />
--Lrollvariables|FirstCardVars<br />
</pre><br />
<br />
When loading settings, all stored settings will be applied to the current card settings. You can override settings by changing them after the load.<br />
<br />
When loading roll variables, the saved variables will be added to (or overwrite if they have the same name) any variables on the current card. This means it is safe to create roll variables before the load statement.<br />
<br />
'''Practical Uses'''<br />
The major intended use of persistent storage is for storing card formats for use in later scripts. For example, the following script:<br />
<br />
<pre><br />
!scriptcard {{<br />
--#titlecardbackground|#22CC22<br />
--#oddrowbackground|#cceecc<br />
--#evenrowbackground|#99ee99<br />
--Ssettings|@{selected|token_name}<br />
}}<br />
</pre><br />
<br />
Would save the titlecardbackground, oddrowbackground, and evenrowbackground settings to a saved list named after the selected token's name. When creating cards for that token to run later, you could include the line:<br />
<br />
<pre><br />
--Lsettings|@{selected|token_name}<br />
</pre><br />
<br />
To load all of the settings at once. By creating these setting sets for each character, you can specify a different color scheme for each character that can then be used in cards with a single formatting line.<br />
<br />
There is a supplemental ! command added to support saved settings:<br />
<br />
<pre><br />
!sc-liststoredsettings<br />
</pre><br />
<br />
Will produce a list of all stored setting names, with buttons to list the setting values stored in each group and a button to delete groups as needed.<br />
<br />
=== Visual Effects (--v) ===<br />
<br />
The --v statement can be used to create visual effects on the tabletop. The tag portion of the statement can be either "token" or "betweentokens". The content portion of the statement contains the required parameters for the effect generation, separated by spaces. If the effect is "none", no effect will be played. If any other value that doesn't match a Roll20 effect name will result in a burst-fire effect.<br />
<br />
For "token" effects, the parameters are the token id for the token the effect happens on, followed by the effect specifier.<br />
<br />
Example:<br />
<pre><br />
--vtoken|@{selected|token_id} burst-fire<br />
</pre><br />
<br />
For "betweentoken" effects, the parameters are the source token id, the target token id, and the effect specifier.<br />
<br />
Example:<br />
<pre><br />
--vbetweentokens|@{selected|token_id} @{target|token_id} beam-magic<br />
</pre><br />
<br />
'''''Version 1.2.8+'''''<br />
<br />
An additional effect specifier, "point" is available in 1.2.8+. This specifier allows you to create a visual effect at a designated X/Y pixel coordinate. Future updates will add custom-vfx support to this option. The parameters are the X and Y coordinates and the effect descriptor. As of version 1.2.9, you can also use custom effect specifiers with Point effects:<br />
<br />
<pre><br />
--vpoint|150 200 burst-fire<br />
</pre><br />
<br />
=== Echo to Chat (--e) ===<br />
<br />
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.<br />
<br />
Example:<br />
<pre><br />
--eThe Ghost|/em hovers around @{selected|character_name}... BOO!<br />
</pre><br />
<br />
Would output "The Ghost hovers around (charactername)... BOO!" as an emote to chat.<br />
<br />
=== Repeating Section Access (--R) ===<br />
<br />
ScriptCards (as of v0.0.13) supports accessing repeating section rows on a character sheet with the --R statement type. <br />
<br />
There are three basic commands you can use with --R, and they are specified by the tag used:<br />
<br />
<pre><br />
--Rfind|characterid;EntryName;SectionPrefix;SearchField<br />
</pre><br />
<br />
This is the most direct way to access a repeating section row. Supplying the character ID, followed by what you are looking for (Greatsword, for example), followed by the character sheet's section prefix (repeating_attack), followed by the field to check what you are searching for (atkname) will load the matching section (if found) into the script parsers memory. For example:<br />
<br />
<pre><br />
--Rfind|@{selected|character_id};Greatsword;repeating_attack;atkname<br />
</pre><br />
<br />
Will look at the character's "repeating_attack" section for an entry with an atkname value equal to "Greatsword". Similarly:<br />
<br />
<pre><br />
--Rfind|@{selected|character_id};Bite;repeating_npcaction;name<br />
</pre><br />
<br />
Will look for a "Bite" action on an NPC's action list.<br />
<br />
<pre><br />
--Rfirst|characterid;section prefix<br />
</pre><br />
<br />
This form of the --R command will look at all of the entries in the specified repeating section and load the first one into memory:<br />
<br />
<pre><br />
--Rfirst|@{selected|character_id};repeating_attack<br />
</pre><br />
<br />
Would load the character's first "repeating_attack" row into memory.<br />
<br />
<pre><br />
--Rnext|<br />
</pre><br />
<br />
No parameters are required for --Rnext, which loads the next entry in the list that was obtained with "first" into memory.<br />
<br />
However a row is obtained, it will be parsed to replace any attribute references (ie, @{level}) with the corresponding character attribute.<br />
<br />
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".<br />
<br />
You can reference repeating attribute data using the syntax [*R:attributename] syntax (similar to referencing standard character attributes).<br />
<br />
Here are some examples:<br />
<br />
Display the details of the "Greatsword" PC attack:<br />
<br />
<pre><br />
!script {{<br />
--Rfind|@{selected|character_id};Greatsword;repeating_attack;atkname<br />
--+Attack Name|[*R:atkname]<br />
--+Base Damage|[*R:dmgbase]<br />
}}<br />
</pre><br />
<br />
[[File:Scriptcards repeating greatsword.png|Repeating Greatsword Attack]]<br />
<br />
List all of the actions an NPC can take (just actions, not legendary, etc.)<br />
<br />
<pre><br />
!script {{<br />
--#title|NPC Actions<br />
--#leftsub|@{selected|token_name}<br />
--Rfirst|@{selected|character_id};repeating_npcaction<br />
--:DisplayLoop|<br />
--?"[*R:name]" -eq NoRepeatingAttributeLoaded|Done<br />
--+Action:|[*R:name] [*R:attack_damage] [*R:attack_damagetype]<br />
--?"[*R:attack_damage2]" -eq ""|NoSecondaryDamage<br />
--+ |[*R:attack_damage2] [*R:attack_damagetype2]<br />
--:NoSecondaryDamage|<br />
--Rnext|<br />
-->DisplayLoop| <br />
--:Done|<br />
}}<br />
</pre><br />
<br />
[[File:Scriptcards repeating npcactions.png]]<br />
<br />
In the script above, we get the "first" repeating_npcaction and display information about it. We then execute "next" and repeat until we run into "NoRepeatingAttributeLoaded".<br />
<br />
'''''Special debugging command: dump'''''<br />
<pre><br />
--Rdump|<br />
</pre><br />
<br />
The "dump" command will list all of the attributes ScriptCards knows about for the currently loaded repeating row to the API Console Log.<br />
<br />
=== Assign Variable to Built-In Function (--~) ===<br />
<br />
ScriptCards has the ability to run a function built into the API script and return the results to a variable. Some functions return roll variables, while others return strings. See the function table below for details. The format is:<br />
<br />
--~VariableName|function;param1;param2;param3;...<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Function Name !! Parameters !! Description<br />
|-<br />
| distance || token_A_ID;token_B_ID || Calculate the Chebyshev distance in grid units between two tokens. This is the measurement scheme D&D 4E/5E use for diagonal distance measurement<br />
|-<br />
| euclideandistance || token_A_ID;token_B_ID || Calculate the Euclidean distance between two tokens. This is essentially the Pythagorean theorem in action. Returns the result in grid units.<br />
|-<br />
| euclideanpixel || token_A_ID;token_B_ID || Calculate the Euclidean distance between two tokens and returns the result is pixels instead of grid units. <br />
|-<br />
| euclideanlong || token_A_ID;token_B_ID || 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 is calculated instead of before. More accurate over long distances. <br />
|-<br />
| manhattandistance || token_A_ID;token_B_ID || Also called "taxicabdistance" (which is an acceptable function name), this measures to how-many-over, how-many-up/down distance, disallowing diagonal movement.<br />
|-<br />
| getselected || none || 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 the first selected token, VariableName2 the second, etc.<br />
|}<br />
<br />
'''''Functions with Sub Functions'''''<br />
<br />
Most ScriptCards functions are grouped into set as sub functions. The table below lists the major functions and their sub functions.<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Function Name !! Sub Function !! Parameters !! Return Type !! Description<br />
|-<br />
| array || define || arrayname;value1;value2;... || none || Creates an array called "arrayname" and adds value1, value2, etc. to the array<br />
|-<br />
| array || sort || arrayname || none || Sorts the specified array in place in ascending order<br />
|-<br />
| array || add || arrayname;value1;value2;... || none || Adds value1, value2, ... to the existing array "arrayname"<br />
|-<br />
| array || remove || arrayname;value1;value2;... || none || Removes value1, value2, ... from the existing array "arrayname". Resets the array index to 0.<br />
|-<br />
| array || replace || arrayname;currentvalue;newvalue || none || Replaces all occurrences of "currentvalue" in "arayname" with "newvalue"<br />
|-<br />
| array || setatindex || arrayname;index;newvalue || none || Replaces the array item at index "index" with "newvalue"<br />
|-<br />
| array || getindex || arrayname || stringVariable || Retrieves the current index in "arrayname" and stores it in the supplied string variable<br />
|-<br />
| array || setindex || arrayname;newindex || none || Sets the current index in array "arrayname" to "newindex"<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| 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.<br />
|-<br />
| array || removeat || arrayname;indexposition || none || Removes the item at index "indexposition" from "arrayname". Resets the current array index to 0.<br />
|-<br />
| array || indexof || arrayname;searchvalue || stringVariable || Searches the array "arrayname" for and item with the value of "searchvalue" and, if found, returns the index of the first matching value or "ArrayError" if not found<br />
|-<br />
| array || getlength || arrayname || stringVariable || Returns the number of items in array "arrayname"<br />
|-<br />
| array || pagetokens || arrayname;tokenid;(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. 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.)<br />
|-<br />
| 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.<br />
|-<br />
| array || stringify || arrayname || stringVariable || Returns all of the items in "arrayname" as a string separated by semicolons (;)<br />
|-<br />
| array || fromstring || arrayname || delimiter;string || Creates an array from "string", splitting "string" on "delimiter" to separate the items<br />
|-<br />
| array || statusmarkers|| arrayname;tokenid || none|| Creates an array (arrayname) of the active statusmarkers (sometimes called Token Markers) for the specified tokenid<br />
|-<br />
| math || angle || math;angle;tokenid;tokenid|| rollVariable || Calculates the angle between two tokens and returns the value in degrees<br />
|-<br />
| math || ceil || math;ceil;value || rollVariable || Rounds '''value''' up to the next integer, dropping any decimal portion of the number<br />
|-<br />
| math || clamp || math;clamp;value;lowerBound;upperBound || rollVariable || Returns '''value''', but restricted to the range of '''loweBound''' and '''upperBound'''.<br />
|-<br />
| math || floor || math;floor;value || rollVariable || Rounds '''value''' down, dropping any decimal portion of the number<br />
|-<br />
| math || max || math;max;valueA;valueB || rollVariable || Returns the larger of '''valueA''' vs '''valueB'''<br />
|-<br />
| math || min || math;min;valueA;valueB || rollVariable || Returns the smaller of '''valueA''' vs '''valueB'''<br />
|-<br />
| math || round || math;round;value || rollVariable || Rounds '''value''' to the nearest integer<br />
|-<br />
| string || length || string;length;stringValue || rollVariable || Returns the length of '''stringValue''' in characters<br />
|-<br />
| string || before || string;before;searchText;stringValue || stringVariable || Searches '''stringValue''' for '''searchText''' and returns the portion of '''stringValue''' prior to that text<br />
|-<br />
| string || after || string;after;searchText;stringValue || stringVariable || Searches '''stringValue''' for '''searchText''' and returns the portion of '''stringValue''' after that text<br />
|-<br />
| string || left || string;left;count;stringValue || stringVariable || Returns the leftmost '''count''' characters of '''stringValue'''<br />
|-<br />
| string || right || string;right;count;stringValue || stringVariable || Returns the rightmost '''count''' characters of '''stringValue'''<br />
|-<br />
| string || replace || string;replace;searchText;replaceText;stringValue || stringVariable || Replaces '''searchText''' in '''stringValue''' with '''replaceText''' and returns the resulting string<br />
|-<br />
| string || replaceall || string;replace;searchText;replaceText;stringValue || stringVariable || Replaces all intances of '''searchText''' in '''stringValue''' with '''replaceText''' and returns the resulting string '''''Requires 1.2.9+'''''<br />
|-<br />
| string || trim || string;trim;stringValue || stringVariable || Removes leading and trailing spaces from stringValue and returns the result. <br />
|-<br />
| string || substring || string;substring;start;count;stringValue || stringVariable || Returns '''count''' characters starting at '''start''' from '''stringValue'''<br />
|-<br />
| 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.<br />
|-<br />
| string || tolowercase || string;tolowercase;stringValue || stringVariable || Converts the passed string to lower case and assigns to the passed variable name. <br />
|-<br />
| string || touppercase || string || stringVariable || Converts the passed string to upper case and assigns to the passed variable name. <br />
|-<br />
| 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. <br />
|-<br />
| 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.<br />
|-<br />
| 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'''.<br />
|-<br />
| turnorder || clear || none || none || Clears all entries from the {{Turn Tracker}}/Initiative<br />
|-<br />
| turnorder || addtoken || tokenid;trackervalue || none || Adds the token represented by "tokenid" to the initiative tracker with an initiavie value of "trackervalue"<br />
|-<br />
| turnorder || replacetoken || tokenid;trackervalue || none || Replaces the token represented by "tokenid" in the initiative tracker with an initiavie value of "trackervalue". Will add the token if it doesn't exist in the tracker.<br />
|-<br />
| turnorder || removetoken || tokenid || none || Removes the token represented by "tokenid" from the initiative tracker if it exists<br />
|-<br />
| turnorder || addcustom || textlabel;trackervalue || none || Add a custom text entry to the {{Turn Tracker}}/Initiative named "textlabel" with an initiative value of "trackervalue"<br />
|-<br />
| system || date || getdatetime || stringVariable || Returns the date time in the active timezone (see settings) <br />
|-<br />
| system || date || getdate || stringVariable || Returns the date in the active timezone (see settings) <br />
|-<br />
| system || date || gettime || stringVariable || Returns the time in the active timezone (see settings)<br />
|-<br />
| system || dumpvariables || "rolls", "string", or "array" || none || Dumps all of the defined variables of the indicated type to the console log<br />
|-<br />
| system || findability || system;findability;charactername;abilityname || stringVariable || Returns the object ID of the ability on the indicated character or "AbilityNotFound"<br />
|-<br />
|}<br />
<br />
Examples:<br />
<br />
<pre><br />
--~HowFarAway|distance;@{selected|token_id};@{target|token_id}<br />
</pre><br />
<br />
Returns the distance (Chebyshev) between the selected and target tokens and stores it in "HowFarAway".<br />
<br />
<pre><br />
--SelectedDudes|getselected<br />
</pre><br />
<br />
If 5 tokens were selected, 6 variables would be created: SelectedDudesCount (with a value of 5), SelectedDudes1, SelectedDudes2, SelectedDudes3, SelectedDudes4, SelectedDudes5.<br />
<br />
=== Information Request (--i) ===<br />
<br />
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.<br />
<br />
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.<br />
<br />
After the user has clicked the button and responded to the requests, ScriptCards will resume processing the script from where it left off.<br />
<br />
Here is an example “i” line:<br />
<br />
<pre><br />
--IScriptCards needs additional information to continue;Click to select a target and provide information|t;MyNewTarget;Missile1Target||q;MyNameIs;What is your name?<br />
</pre><br />
<br />
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.<br />
<br />
Supported information request types are “t” for target token, and “q” for query.<br />
<br />
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).<br />
<br />
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:<br />
<br />
<pre><br />
q;UserName;What is your name?|Fred|Bob|Sally|Nancy<br />
</pre><br />
<br />
Would have a dropdown menu with four choices.<br />
<br />
== Inline Formatting ==<br />
<br />
Inline formatting is processed on Direct Output lines only (--+ lines) and the following inline format markup is available:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Formatting Tags !! Description<br />
|-<br />
| [b]..[/b] || Bold the text between the markers <br />
|-<br />
| [i]..[/i] || Italicize the text between the markers <br />
|-<br />
| [u]..[/u] || Underline the text between the markers <br />
|-<br />
| [s]..[/s] || Strike-Thru the text between the markers <br />
|-<br />
| [c]..[/c] || Center alignment <br />
|-<br />
| [l]..[/l] || Left alignment <br />
|-<br />
| [r]..[/r] || Right alignment <br />
|-<br />
| [j]..[/j] || Full justification alignment <br />
|-<br />
| [#xxx]..[/#] or [#xxxxxx]..[/#] || Use a 3 or 6 digit hex code to colorize the text between the markers <br />
|-<br />
| [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, <code>[img width=128 height=128]</code> )<br />
|-<br />
| [button]caption::action[/button] || Create a button with the label "caption" that performs the action defined by "action". <br />
|-<br />
| [t] || Converted to HTML table tag. Text after the "t" will be included inside the tag (width, border, etc)<br />
|-<br />
| [/t] || Converted to HTML close table tag.<br />
|-<br />
| [tr] || Converted to HTML table row tag. Text after the "tr" will be included inside the tag<br />
|-<br />
| [/tr] || Converted to HTML close table row tag.<br />
|-<br />
| [td] || Converted to HTML table cell tag. Text after the "tr" will be included inside the tag<br />
|-<br />
| [/td] || Converted to HTML close table cell tag.<br />
|}<br />
<br />
== Variables ==<br />
<br />
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. While it is possible to assign both a string and a roll variable the same name, doing so will likely result in confusion when looking at the script later, so it is not recommended.<br />
<br />
String Variables are assigned with the --& statement and are referenced using [&variableName] notation.<br />
<br />
Roll Variables are assigned with the --= statement, and the assignment value is always processed by the ScriptCards Roll Processor (resolves dice rolls, etc.)<br />
<br />
There are a handful of variables assigned automatically when a ScriptCard is executed. These are all string variables, and are:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Variable !! Value<br />
|-<br />
| SendingPlayerID || Contains the object ID of the player that sent the macro<br />
|-<br />
| SendingPlayerName || Contains the display name of the player<br />
|-<br />
| SendingPlayerColor || Contains the color code associated with the player<br />
|-<br />
| SendingPlayerSpeakingAs || The contents of the "Speaking As" dropdown window<br />
|-<br />
| SendingPlayerIsGM || Contains 1 if the player is a GM, and 0 if the player is NOT a GM<br />
|}<br />
<br />
== Arrays ==<br />
<br />
Arrays are a special type of variable, and are managed by the function (<nowiki>--~</nowiki> command). All of the array function commands follow the same pattern:<br />
<br />
<pre>--~variableName|array;subcommand;arrayname;param1;param2;param3;...</pre><br />
<br />
Not all array commands return anything to "variableName". The function table above will specify the return type of the command if any.<br />
<br />
There are a couple of different ways to create an array:<br />
<br />
The '''define''' array subcommand creates (or recreates) an array and assigns it values - one for each included parameter after the array name. For example:<br />
<br />
<pre>--~|array;define;Fruits;mango;peach;strawberry;apricot;banana;apple</pre><br />
<br />
will create an array called '''Fruits''' with 6 elements in the order listed in the command (mango, peach, etc.)<br />
<br />
You can also use two other subcommands to create arrays based on tokens:<br />
<br />
<pre>--~Count|array;pagetokens;Everybondy;@{selected|token_id}</pre><br />
<br />
and<br />
<br />
<pre>--~Count|array;selectedtokens;Selected</pre><br />
<br />
In both cases, arrays of tokens will be created, and a string variable called "Count" will be set to the number of tokens in the array. The '''pagetokens''' command returns (by default) all of the tokens on the page that contains the token passed as the parameter after the array name. You can filter the tokens that "pagetokens" includes in the array by appending an optional parameter describing the type of token you are looking for:<br />
<br />
<pre>--~Count|array;pagetokens;Everybondy;@{selected|token_id};npc</pre><br />
<br />
Will return only tokens on the page that represent characters that do not have a ''controlledby'' parameter set. The available options are "all" (default), "char", "graphic", "pc", and "npc".<br />
<br />
The '''selectedtokens''' command returns an array with all of the tokens that were selected when the script was called.<br />
<br />
You can also use an arbitrary string to create an array, specifying a delimiter with the '''fromstring''' command:<br />
<br />
<pre><br />
--&names|Fred<br />
--&names|+,Sally<br />
--&names|+,Ted<br />
--&names|+,Joyce<br />
--~|array;fromstring;,;[&names]<br />
</pre><br />
<br />
The above example builds a comma-separated string and then uses "fromstring" to create an array with 4 elements from it, specifying the comma as the delimiter.<br />
<br />
Finally, you can use the '''statusmarkers''' command to create an array with one entry for each active status marker on a specified token:<br />
<br />
<pre>--~|array;statusmarkers;Conditions;@{selected|token_id}</pre><br />
<br />
will create an array with one entry for each status active on the selected token. The array elements will be the internal name of the status (if you are using custom status marker packs, the names will be specified in the marker pack).<br />
<br />
'''Traversing Arrays'''<br />
<br />
Each array keeps track of an internal index position (starting at 0). Several commands let you manage this index:<br />
<br />
*'''getindex''' returns the current index value<br />
*'''setindex''' sets the index to the specified location in the array<br />
*'''getlength''' returns the number of elements in the array<br />
*'''indexof''' returns the index location of the specified element<br />
<br />
Other commands let you retrieve values from the array:<br />
<br />
*'''getfirst''' sets the index to 0 and returns the value at that position<br />
*'''getnext''' advances the index by 1 and returns the new current value<br />
*'''getprevious''' reduces the index by 1 and returns the new current value<br />
*'''getlast''' sets the index to the last elements in the array and returns the new current value<br />
<br />
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.<br />
<br />
'''Manipulating Array Elements'''<br />
<br />
Several array commands deal with inserting, removing, and modifying elements:<br />
<br />
*'''add''' works just like define, except that it takes an existing array and adds elements to it based on the passed parameters<br />
*'''remove''' looks for items matching each passed parameter and removes them from the indicated array if they exist<br />
*'''removeat''' allows you to specify an index location in the array and remove the element at that position<br />
*'''replace''' searches an array for a value and replaces all occurrences of it with a new value (if found)<br />
*'''sort''' sorts the elements in the array in ascending order<br />
*'''strinfigy''' returns a string variable that includes each array element separated by semicolons (;) <br />
<br />
'''Referencing Array Elements'''<br />
<br />
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.<br />
<br />
<pre><br />
!script {{<br />
--~dummy|array;pagetokens;myarray;@{selected|token_id}<br />
--~count|array;getcount;myarray<br />
--+Total:|There are [&count] graphical objects on the page<br />
--~testvar|array;getfirst;myarray<br />
--:loop|<br />
--+Value|[*[&testvar]:character_name]<br />
--~testvar|array;getnext;myarray<br />
--?[&testvar] -ne ArrayError|loop<br />
--+Loop1|Is Done!<br />
}}<br />
</pre><br />
<br />
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:<br />
<br />
<pre><br />
!script {{<br />
--~dummy|array;pagetokens;myarray;@{selected|token_id}<br />
--~count|array;getcount;myarray<br />
--+Total:|There are [&count] graphical objects on the page<br />
--%loopCounter|1;[&count]<br />
--+Value|[*[@myarray([&loopCounter])]:character_name]<br />
--%|<br />
--+Loop|Is Done!<br />
}}<br />
</pre><br />
<br />
This line : <nowiki>--+Value|[*[@myarray([&loopCounter])]:character_name]</nowiki> uses [@arrayName(index)] format (inside a [*characterid:attribute] syntax) to perform the same task as running through the loop with the index.<br />
<br />
(Note: Additional examples are on the way...)<br />
<br />
== For...Next Loops ==<br />
<br />
For...Next loops in ScriptCards are supported with the with the --% statement type. A loop is defined by starting off with:<br />
<br />
<pre><br />
--%LoopCounter|<start>;<end>;[step]<br />
</pre><br />
<br />
The start and end values are required, while the step parameter is optional. If the step is omitted, it will be assumed to be 1. A string variable named after the line tag ("LoopCounter" in the case above) will be created and will hold the current iteration value for the loop. Here is a real example:<br />
<br />
<pre><br />
--%LoopCounter|1;10;1<br />
</pre><br />
<br />
This will begin a loop identified by "LoopCounter" that will start at 1, increasing by 1 each iteration (the step) until it has completed 10 executions.<br />
<br />
The "next" statement is simply <code>--%|</code>, with no tag or parameters. This indicates to ScriptCards that it should increment the counter and go back to the beginning of the loop. Extending the example above:<br />
<br />
<pre><br />
!script {{<br />
--%LoopCounter|1;10;1<br />
--=Roll|1d20<br />
--+Loop|Counter is [&LoopCounter], roll was [$Roll]<br />
--%|<br />
}}<br />
</pre><br />
<br />
The <code>--%!|</code> sequence will break out of the loop, no matter how many iterations are remaining.<br />
<br />
The % and %! character sequences can also be used as part of a 1.2.1+ non-branching conditional to continue or break the loop:<br />
<br />
<pre><br />
--?"X[&RollInto]X" -eq "XX"|%<br />
</pre><br />
<br />
In this example, if the string variable RollInfo is empty, the loop will return to the top and continue with the next iteration, while:<br />
<br />
<pre><br />
--?"X[&RollInto]X" -eq "XX"|%!<br />
</pre><br />
<br />
Would cause the whole loop to end if the condition were true.<br />
<br />
== Referencing ==<br />
<br />
=== Roll Variables===<br />
<br />
Roll Variables can be referenced from the content portion of any line type, and from the tag portion of conditional statements. The referenced value is replaced when the line is executed.<br />
<br />
There are several modifiers that can be used to reference parts of a roll:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Modifier !! Meaning<br />
|-<br />
| No modifier || In a Direct Output Line (<nowiki>--+</nowiki>), GM Output Line (<nowiki>--*</nowiki>), or String Assignement (<nowiki>--&</nowiki>), 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<br />
|-<br />
| .Total || The end result of the roll equation. Formatting rules for "No Modifier" apply based on line type. <br />
|-<br />
| .Raw || The total value of the roll variable without any formatting, no matter what kind of line the reference is used in.<br />
|-<br />
| .Base || The cumulative result of any dice rolled in the Roll Text (Numeric modifiers are not included) <br />
|-<br />
| .Ones || The number of dice in the roll that came up as 1s <br />
|-<br />
| .Aces || The number of dice in the roll that came up as the maximum number on the die <br />
|-<br />
| .Odds || The number of dice in the roll that came up with an odd number <br />
|-<br />
| .Evens || The number of dice in the roll that came up with an even number <br />
|-<br />
| .RollText || The raw text of the roll that was use to generate the results <br />
|-<br />
| .Text || A text representation of the results of the roll, including the numbers rolled for each die <br />
|-<br />
| .tableEntryText || The text portion of the result of a table roll<br />
|-<br />
| .tableEntryImgURL || The image source portion of the result of a table roll<br />
|-<br />
| .tableEntryValue || If the tableEntryText is purely numeric, will contain the numeric value<br />
|}<br />
<br />
=== String Variables ===<br />
<br />
To reference a string variable, use the notation [&variablename]. String variables can be referenced in direct output, roll variable assignment, and string variable assignment statements.<br />
<br />
=== Character/Token Attributes ===<br />
<br />
A character or token attribute can be referenced from content portion of any type of line and is substituted when the line is executed. The general format for referencing a character attribute is [*ID:attribute]. ID can be a token ID or a character ID (these start with a dash). Additionally if you have specified a sourceToken or targetToken, you can substitute "S" or "T" for the ID (for example [*S:npc_type] will retrieve the npc_type attribute from the source token.<br />
<br />
By default, all attribute references will be pulled from the '''''character''''' object that the ID represents (either directly or by being a Token ID that represents a character).<br />
<br />
If your ID refers to a token, token attributes can be accessed by preceding the attribute name with "t-", for example [*S:t-aura1_radius]. Supported token attributes are:<br />
<br />
{|<br />
| t-name || t-id || t-statusmarkers || t-bar1_value<br />
|-<br />
| t-bar1_max || t-bar2_value || t-bar2_max || t-bar3_value<br />
|-<br />
| t-bar3_max || t-top || t-left || t-width<br />
|-<br />
| t-height || t-rotation || t-layer || t-aura1_radius<br />
|-<br />
| t-aura1_color || t-aura2_radius || t-aura2_color || t-aura1_square<br />
|-<br />
| t-aura2_square || t-tint_color || t-light_radius || t-light_dimradius<br />
|-<br />
| t-light_angle || t-light_losangle || t-light_multiplier || t-light_otherplayers<br />
|-<br />
| t-light_hassight || t-flipv || t-fliph || t-controlledby<br />
|-<br />
| t-_cardid || t-_pageid || t-imgsrc || t-bar1_link<br />
|-<br />
| t-bar2_link || t-bar3_link || t-represents || t-layer<br />
|-<br />
| t-isdrawing || t-name || t-gmnotes || t-showname<br />
|-<br />
| t-showplayers_name || t-showplayers_bar1 || t-showplayers_bar2 || t-showplayers_bar3<br />
|-<br />
| t-showplayers_aura1 || t-showplayers_aura2 || t-playersedit_name || t-playersedit_bar1<br />
|-<br />
| t-playersedit_bar2 || t-playersedit_bar3 || t-playersedit_aura1 || t-playersedit_aura2<br />
|-<br />
| t-lastmove || t-adv_fow_view_distance || t-has_bright_light_vision || t-has_night_vision<br />
|-<br />
| t-night_vision_distance || t-emits_bright_light || t-bright_light_distance || t-emits_low_light<br />
|-<br />
| t-low_light_distance || t-has_limit_field_of_vision || t-limit_field_of_vision_center || t-limit_field_of_vision_total<br />
|-<br />
| t-has_limit_field_of_night_vision || t-limit_field_of_night_vision_center || t-limit_field_of_night_vision_total || t-has_directional_bright_light<br />
|-<br />
| t-directional_bright_light_center || t-directional_bright_light_total || t-has_directional_dim_light || t-directional_dim_light_center<br />
|-<br />
| t-directional_dim_light_total || t-lightColor || || |<br />
|}<br />
<br />
'''''It is important to note that some attributes names on tokens have corresponding attribute names on characters, which represent different values. For example, [*T:id] returns the character ID, while [*T:t-id] returns the token ID.'''''<br />
<br />
=== Subroutine Parameters ===<br />
<br />
When using a gosub statement (-->) or a conditional marked as a gosub (prefixing the label with a > character), you can pass any number of parameters separated by semicolons (;) that the code in the subroutine can utilize.<br />
<br />
Subroutine parameters are numbered starting at 1, and are accessed by using the notation [%number%], so the first parameter is [%1%], the second is [%2%], etc.<br />
<br />
Parameter substitution happens on all line types, and happens prior to character attribute references or roll variable substitution.<br />
<br />
=== Campaign Attribute ===<br />
You can retrieve properties of the API's Campaign object with the [*C:attributename] syntax. For example, [*C:playerpageid] will retrieve the current player ribbon page from the Campaign object.<br />
<br />
=== Page Attributes ===<br />
If you have set the '''activepage''' parameter, you can retrieve page-related properties with the [*P:attributename] syntax, including the page's UDL parameters.<br />
<br />
=== Repeating Section Values ===<br />
<br />
You can reference repeating attribute data using the syntax [*R:attributename] syntax (similar to referencing standard character attributes). The currently active repeating row information will be used to retrieve attribute values. You can also retrieve the full attribute name for a repeating row attribute by using the [*R>attributename] notation. This is useful to pass to things like chatsetattr.<br />
<br />
=== Array Elements ===<br />
After an array has been declared, the elements can be referenced with [@arrayName(index)]. Array indices start at 0.<br />
<br />
== Deferred Resolution for Meta Scripts ==<br />
<br />
As of 1.2.9, ScriptCards supports a deferral character for use when calling another API script with via the --@ statement, to defer processing of meta script references so they get processed prior to the sub-API call insted of prior to ScriptCards execution. To defer this processing for meta script (SelectManager, Fetch) by inserting a deferral character into the meta call. For example, if I want to have ScriptCards call TokenMod as if the token for "Quej Gr'stra" (yes, I let Roll20 name my test NPCs) I could use something like this:<br />
<br />
--@token-mod|{^& select Quej Gr'stra} _on showname<br />
<br />
The "^" in between { and & will prevent SelectManager from seeing the call when the ScriptCard script is processed, but the --@ statement will remove the deferral character so the command that will be sent by ScriptCards is:<br />
<br />
!token-mod {& select Quej Gr'stra} --on showname<br />
<br />
With the deferral character removed, SelectManager will see the {& select ...} and do its magic.<br />
<br />
While the default deferral character is "^", the deferral character is a setting that can be changed:<br />
<br />
--#deferralcharacter|%<br />
<br />
Will make % the deferral character for future --@ statements in the running script.<br />
<br />
There are currently three supported Meta script structures: {^&...} for SelectManager, @^(...) and *^(...) for fetch, where the ^ in the structures here represents the placement of the deferral character.<br />
<br />
== Arrays ==<br />
<br />
Arrays are a new data type introduced in version 1.1.12 of ScriptCards, and are manipulated with associated function (--~) commands.<br />
<br />
* Arrays are a lists of strings. Items in an array cannot contain the semi-colon (;) character, as that is used to separate parameters in the function code that deals with arrays.<br />
* Arrays are accessed via the --~ script command. In some cases, the value of the tag (variable name) for array commands is not used, and can be a dummy value or simply omitted. I have omitted them in the statements below.<br />
* All commands that DO return a value return string values, even if the content is numeric.<br />
* If a command returns a value and there is some sort of reason that it isn't an array value, you will get "ArrayError" in the return value. This can happen if you reach the end of an array while stepping through it, for example, so checking for "ArrayError" can serve as the end condition for a loop.<br />
* Each array keeps track of its current index, allowing you to step forward and backwards through arrays.<br />
* Any number of arrays can be defined.<br />
* Unlike string variables and roll variables, array variables cannot (currently) be referenced directly. It is necessary to use the function (--~) syntax to manipulate arrays and get values from them as strings for use in other parts of your script.<br />
<br />
<br />
== Reentrant Scripts ==<br />
<br />
Reentrant scripts allow you to create buttons in your script code that will re-execute the script at a given label within the code. If you set the reentrant setting (--#reentrant|somevalue) to a non-zero value, your setting and variable information will be preserved between executions. Reentrant script can be used to present menus or choices and then continue acting.<br />
<br />
Reentrant buttons are created with the [rbutton]Caption::ReentryLabel;Parameter[/rbutton] construct. The caption will be displayed on the generated button. ReentryLabel is the name of a label in your script that the button will jump to when clicked, and Parameter will be passed in as a string value called "reentryval".<br />
<br />
Example:<br />
<pre><br />
!script {{<br />
--#reentrant|testing<br />
--=Roll|1d20<br />
--+Roll|[$Roll]<br />
--&String|That was a [$Roll.Raw]!<br />
--~x|array;define;MyArray;Apple;Banana;Orange<br />
--+Try it|[rbutton]Hello!::EXEC_PC_SPELL;9[/rbutton]<br />
--X|<br />
<br />
--:EXEC_PC_SPELL|<br />
--+ReentryVal|[&reentryval]<br />
--+The value of Roll is|[$Roll]<br />
--+Value of String|[&String]<br />
--+Array|[@MyArray(0)]<br />
--X|<br />
}}<br />
</pre><br />
<br />
This script sets up some variables and then displays a button labeled "Hello!". If the user clicks the button, the script will be re-entered starting at the "EXEC_PC_SPELL", which will display the content of the variables from the original execution.<br />
<br />
'''''Note: This section needs to be expanded upon'''''<br />
<br />
== Procedure Libraries ==<br />
<br />
You can now create handouts in your game in Roll 20 with the name format "ScriptCards Library NAME", where name is a name you assign to the library. Library names are case sensitive. It is my hope that the more proficient ScriptCards scripters out there will provide procedure libraries (or procedures that can be included in libraries) for others to use to make their scripting life easier. Be they specific to a game system, or to a type of activity, I think a robust set of libraries that GMs could use to enhance their scripting capabilities would be very valuable to the community. Should such things begin to emerge, I’ll create a portion of the ScriptCards Wiki page to house them.<br />
<br />
To include one or more libraries in a script, use the +++libname+++ directive (does not need a -- line associated with it). Multiple library names can be specified by separating them with semicolons (i.e., +++General;dnd5elib;Colorize+++ would include three libraries (General, dnd5elib, and Colorize).<br />
<br />
Included libraries are separated from the main script code by the automatic inclusion of "--X|" before the first library is appended to the script, and all libraries are loaded at the end of the script before script processing takes place.<br />
<br />
Procedures and labels in libraries can be used just as if they were included in the body of your script. Note that this DOES mean that you could, technically, jump into a library with a direct branch (--^) or direct branch conditional, but I recommend using libraries to store reusable procedures.<br />
The Notes section of the library handout stores the library code, and is written just like any other ScriptCards code except:<br />
<br />
* They cannot use roll queries (?{Some Prompt:}) to get information from the user at execution time.<br />
* They cannot use @{} notation to access character and token information.<br />
<br />
Both of these limitation stem from the fact that Procedure Libraries are not processed by the chat server, which is what handles these items.<br />
<br />
Here is an example of handling damage modifications (resistance, vulnerability, and immunity) in D&D 5E with a library:<br />
<br />
<pre><br />
!script {{<br />
+++dnd5elib+++<br />
--#|Damage Modifiers Test<br />
--#targettoken|@{target|token_id}<br />
-->Lib5E_CheckDamageModifiers|ResistType;fire<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] fire damage<br />
<br />
-->Lib5E_CheckDamageModifiers|ResistType;cold<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] cold damage<br />
<br />
-->Lib5E_CheckDamageModifiers|ResistType;poison<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] poison damage<br />
<br />
-->Lib5E_CheckDamageModifiers|ResistType;acid<br />
--=DamageRoll|2d10 [&ResistType]<br />
--+Test:|[$DamageRoll] acid damage<br />
<br />
--X|<br />
}}<br />
</pre><br />
<br />
Library content (In a handout called “ScriptCards Library dnd5elib” NOTE: Paste into Notepad first and then paste into the handout in Roll20 to avoid bringing over HTML formatting from the web site):<br />
<br />
<pre><br />
--/|ScriptCards Library: dnd5elib version 0.0.1<br />
--/|Provides various utility procedures for D&D 5E games<br />
<br />
--/|Lib5E_CheckDamageModifiers handle damage resistance, vulnerability, and immunity. <br />
--/|Pass a string variable to be filled with a string to be appended to a dice roll and the damage type <br />
<br />
--:Lib5E_CheckDamageModifiers|damageVariableName;damageType<br />
--&[%1%]|<br />
--?"[*T:npc_vulnerabilities]" -inc "[%2%]"|>_Lib5E_IsVulnerable;[%1%]<br />
--?"[*T:npc_resistances]" -inc "[%2%]"|>_Lib5E_IsResistant;[%1%]<br />
--?"[*T:npc_immunities]" -inc "[%2%]"|>_Lib5E_IsImmune;[%1%]<br />
--<|<br />
<br />
--:_Lib5E_IsVulnerable| --&[%1%]| * 2 [Vulnerable] --<|<br />
--:_Lib5E_IsResistant| --&[%1%]| \ 2 [Resistant] --<|<br />
--:_Lib5E_IsImmune| --&[%1%]| * 0 [Immune] --<|<br />
</pre><br />
<br />
The idea is that the functions in the library create a string that can be appended to a roll to modify the output based on resistances, so you pass Lib5E_CheckDamageModifiers the name of the string variable you want to use and the damage type. The variable (ResistType in this case) will include either nothing, “* 2 [Vulnerable]”, “\ 2 [Resistant]”, or “* 0 [Immune]” which can be included in a roll assignment (--=) to modify the damage as appropriate. The order here might be important if an NPC is misconfigured to be both resistant and immune to the same damage type. Since immune is an absolute, having it last ensures that it will override resistant or vulnerable. A creature that is both vulnerable and resistant (again, misconfigured) will come back as resistant since that condition is checked after vulnerable.<br />
Some notes: I prefix my library labels with either “Lib5E_” or “_Lib5E_” as a clarity convention. This isn’t strictly necessary but you should be aware that if two libraries (or if your script and a library) define the same label, the last label defined will win. Since libraries are appended to the end of the script in the order you include them in the +++libname+++ directive, you can somewhat control this, but it is probably best to avoid re-declaring labels. <br />
<br />
In my case, items beginning with “Lib5E_” are intended to be called by scripts, while items beginning with “_Lib5E_” are intended to be used as subroutines by the “public” procedures. Of course, there is no reason you couldn’t call them directly.<br />
<br />
You might also note that I’ve included some library information in comment lines (--/|) at the top of the library. These are ignored by ScriptCards, and are a good way to convey requirements, parameters, usage information, etc.<br />
<br />
== Example Libraries ==<br />
<br />
=== dnd5elib ===<br />
<br />
[https://github.com/kjaegers/ScriptCards Download the dnd5elib Library from the ScriptCards GitHub]<br />
<br />
The '''dnd5elib''' library provides a collection of utility procedures that help simplify dealing with the D&D 5E Official Sheet. Some of the procedures in this library require '''chatsetattr''' to be installed in your game. This is a growing library, and currently only has a handful of routines. They are:<br />
<br />
::{| class="wikitable"<br />
|-<br />
! Procedure Name !! Notes<br />
|-<br />
| style="white-space:nowrap" | Lib5E_CheckDamageModifiers || This procedure can be used to evaluate vulnerabilities, resistances, and invulnerabilities on an NPC. After setting the --#target| parameters, pass the Lib5E_CheckDamageModifiers procedure a variable name (no reference information) and a damage type (i.e., fire, cold, bludgeoning, etc.) and a string variable with the name passed in as the first parameter will be created that contains text that can be included in a roll line (--=) in order to modify the roll as appropriate. For example, '''-->Lib5E_CheckDamageModifiers|ResistType;fire''' will check the current target character's attributes for "fire" and will either return an empty string (no references), "* 0 [Immune]" if the creature is immune, "\ 2 [Resistant]" if the creature is resistant, or "* 2 [Vulnerable]" if the creature is vulnerable to fire damage.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_DeductSpellSlot || Pass in a character_id and a slot level, and the script will expend one spell slot of that level, capping the value at 0 slots remaining. For Example '''<nowiki>-->Lib5E_DeductSpellSlot|@{selected|character_id};1</nowiki>''' to deduct a first level spell slot from the selected character.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_FindResource || Used to locate a resource value on a character. Pass in a character_id, a resource name, and two variable names. The procedure will check both repeating and non-repeating resources looking for a resource whose name matches what was passed in and return three variables. The first will be a string variable named for the 3rd parameter and contains the attribute name of the resource's "name" field. The second will be a string variable named after parameter 4 and contains the resource's value field attribute name, and the third variable is a Roll Variable, also named after the 4th parameter that contains the current resource value. Example: '''<nowiki>-->Lib5E_FindResource|@{selected|character_id};Crossbow bolts;ResName;ResValue</nowiki>''' will find "Crossbow bolts" as a resource on the character and return [&ResName] which is the name of the resource attribute, [&ResValue] which is the '''name of the attribute that stores the value''' and [$ResValue] which is the current numeric value of the resource.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Global_Attack_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Attack Modifiers (repeating_tohitmod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Bless" for 1d4 active and "Being Cool" for +2 active, I will get a return string " + 1d4 [Bless] + 2 [Being Cool]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Save_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Save Modifiers (repeating_savemod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Bless" for 1d4 active and "Being Cool" for +2 active, I will get a return string " + 1d4 [Bless] + 2 [Being Cool]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Skill_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Skill Modifiers (repeating_skillmod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Guidance" for 1d4 active and "Being Cool" for +2 active, I will get a return string " + 1d4 [Guidance] + 2 [Being Cool]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_AC_Modifiers || Pass a character ID and a string variable to set the return value. This procedure will look through the Global Save Modifiers (repeating_savemod_*) for rows that are active (checked on the character sheet) and return a string with the dice rolls and descriptions for each (for example, if I have "Shield of Faith" with a value of 2 active, I will get a return string " + 2 [Shield of Faith]" that can be used in a dice roll.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Active_Damage_Modifiers || Pass a character ID and TWO string variable to set the return value. The first string will be for normal damage, and the second will be the additional damage on a crit. This procedure will look through the Global Damage Modifiers (repeating_damagemod_*) for rows that are active (checked on the character sheet) and return two strings with the dice rolls and descriptions for them (for example, if I have "Sneak Attack" with a value of 1d6 normal and 1d6 critical damage active, I will get a return string " + 1d6 [Sneak Attack]" and another string of " + 1d6 [Sneak Attack CRIT]" that can be used in a dice rolls.<br />
|-<br />
| style="white-space:nowrap" | Lib5E_DivineSmiteDice || Used to calculate the number of dice to be rolled for a paladin's Divine Smite. Pass a target token id, a spell slot level, and a string variable to be set to the dice roll amount based on the NPC_TYPE attribute of the target token. The returned variable will contain a dice roll (like "3d8" that can be used in a --= line)<br />
|-<br />
| style="white-space:nowrap" | Lib5E_Character_Summary || Outputs a mini character sheet, including clickable buttons for attacks, actions, legendary actions, etc. Will automatically detect a PC vs NPC and output the appropriate sections.<br />
|}<br />
<br />
Due to formatting issues with the Wiki, the library code has been moved to a [https://gist.github.com/kjaegers/52f6049ddd257f0a1288aca4bbde13c5 GITHUB GIT]. Please view the GIST in raw mode and copy the text and paste it into a handout called "ScriptCards Library dnd5elib" in your Roll20 Game.<br />
<br />
== What to Know if you are Coming from PowerCards ==<br />
<br />
''Note: This section is a work in progress.''<br />
<br />
While ScriptCards and PowerCard have very similar output goals, their internals and use are quite different. The table below summarizes some of the major differences between the scripts.<br />
<br />
::{| class="wikitable"<br />
|-<br />
! PowerCards !! ScriptCards <br />
|-<br />
| With a handful of exceptions, all lines in a PowerCard macro are intended to produce a line of output on the final card. || With ScriptCards, ONLY the <code>--+</code> and <code>--*</code> statement types produces output <br />
|-<br />
| PowerCards lines begin with two dashes (<code>--</code>) followed by a unique tag name for the line, followed by a vertical bar and the content for the line. || ScriptCards lines begin with two dashes (<code>--</code>) followed by a '''statement type identifier''', which is a single character that identifies the type of line to the interpreter. This is followed by a tag (frequently optional), a vertical bar, and the parameters for the statement being executed.<br />
|-<br />
| PowerCard macros are always processed top to bottom. Lines can be hidden so they don't output anything, but there is no looping or branching (--SkipTo looks like a branch, but it just hides all of the lines until the referenced label. || ScriptCards scripts support true branching, including direct branching (<code>--^</code>) and procedure branching (<code>--></code>) and (<code>--<</code>). Procedures support parameters and a call stack so procedures can be nested to call other procedures.<br />
|-<br />
| All lines in a PowerCards macro need to have unique tags because PowerCards builds the card as a single JavaScript object using the tag names to store what will be displayed. This is why repeated tag names always result in the last one being shown. || ScriptCards tags do not need to be unique, and in the case of many line types are optional.<br />
|-<br />
| PowerCards conditionals result in either showing or hiding the line they are on. || ScriptCards conditionals '''''only''''' support branching as the result of the comparison. This branching can be direct (a GOTO) or procedural (a GOSUB) '''''NOTE: As of version 1.2.0, ScriptCards also supports roll/string variable assignment as a result of conditional evaluation'''''<br />
|-<br />
| PowerCards relies on the Roll20 [[Quantum Roll]] server and inline rolls for all dice functions || ScriptCards includes its own dice roll parser, and '''''does not support''''' inline rolls.<br />
|-<br />
| PowerCards RollIDs (often mistaken for variables) are assigned by analyzing the results of an inline roll, and cannot be referenced in other rolls, so you can't roll a <code>1d4</code> and then roll a <code>1d20</code> and add the <code>1d4</code> result because all of the rolls happen on the chat server before PowerCards gets the macro text. || ScriptCards supports two types of variables: Roll Variables and String Variables. Because ScriptCards uses its own roll parser and is not dependent upon the chat server, rolls and their results can be used in other rolls, math functions, output, etc.<br />
|}<br />
<br />
== Example Scripts ==<br />
<br />
Below are some sample scripts that utilize the various statement types in ScriptCards:<br />
<br />
=== Divine Smite ===<br />
<br />
This script will prompt the user for a spell slot level to expend on a divine smite. It will check the target's npc_type to see if it is an Undead or Fiend, which adds an additional d8 to the smite roll.<br />
<br />
[[File:ScriptCards Divine Smite.png|Divine Smite Script Output]]<br />
<br />
<pre><br />
!scriptcard {{<br />
--#title|Divine Smite<br />
--=DiceCount|?{Spell Slot Level?|1|2|3|4|5|6|7|8|9} + 1<br />
--=IsFiendOrUndead|0<br />
--?"@{target|npc_type}" -inc fiend|>IsBoosted<br />
--?"@{target|npc_type}" -inc undead|>IsBoosted<br />
--=TotalDice|[$DiceCount] + [$IsFiendOrUndead]<br />
--=SmiteRoll|[$TotalDice]d8<br />
--#emoteText|@{selected|token_name} smites @{target|token_name}<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
--+Smite|deals [$SmiteRoll] radiant damage.<br />
--X|<br />
<br />
--:IsBoosted|<br />
--=IsFiendOrUndead|1<br />
--<|<br />
}}<br />
</pre><br />
<br />
==== How It Works ====<br />
<br />
The first line sets the "title" card parameter to "Divine Smite".<br />
<br />
Line 2 Shows a query to the user asking for the spell slot level, adds one and stores the value in the "DiceCount" Roll Variable. The query/dropdown is generated by the chat server prior to the script being executed.<br />
<br />
Line 3 defaults the "IsFiendOrUndead" Roll Variable to 0.<br />
<br />
Lines 4 and 5 compare the target's "npc_type" attribute (passed by the chat server as text) to see if they include either "undead" or "fiend". If true, the IsBoosted subroutine will be called. No parameters are passed to this subroutine.<br />
<br />
Line 6 sets the "TotalDice" variable to the base (DiceCount) number plus the IsFiendOrUndead number, which will be a 0 or a 1.<br />
<br />
Line 7 calculates "SmiteRoll" by rolling a number of d8 equal to the "TotalDice" value.<br />
<br />
Lines 8-10 set the parameters for the emote, which appears above the card content. By setting the sourceToken and the targetToken, their icons will appear in the emote surrounding the text describing the action.<br />
<br />
Line 11 is the only line that actually produces output on the card. It results in "Smite deals # radiant damage".<br />
<br />
Line 12 ends the script execution, preventing the script from continuing and running the subroutines out of context.<br />
<br />
Lines 14-16 are the IsBoosted subroutine, starting with the :IsBoosted label. The IsFiendOrUndead variable is set to 1, and a return from subroutine is executed.<br />
<br />
=== Magic Missile ===<br />
<br />
This script demonstrates using a loop and calling a subroutine to fire a number of missiles determine by the spell slot level used to cast the spell.<br />
<br />
[[File:ScriptCards_MagicMissile_Fixed.png|Magic Missile Script Output]]<br />
<br />
<pre><br />
!scriptcard {{ <br />
--#title|Magic Missile<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
--=MissileCount|?{Spell Slot Level?|1|2|3|4|5|6|7|8|9} + 2<br />
--=DisplayCount|1<br />
--=MissileDamage|0<br />
--#leftsub|Slot level ?{Spell Slot Level?}<br />
--#rightsub|Ranged Attack<br />
--#emoteText|Fred uses a level ?{Spell Slot Level?} spell slot to fire [$MissileCount.Total] missiles of magical force!<br />
--:MissileLoop|<br />
-->FireMissile|<br />
--=DisplayCount|[$DisplayCount] + 1<br />
--?[$DisplayCount] -le [$MissileCount]|MissileLoop<br />
--+Total|Total damage is [$MissileDamage]<br />
--X|<br />
<br />
--:FireMissile|<br />
--=ThisMissile|1d4 + 1<br />
--=MissileDamage|[$MissileDamage] + [$ThisMissile]<br />
--+Missile|[$DisplayCount.Total] Hits for [$ThisMissile] [b]force[/b] damage<br />
--<|<br />
}}<br />
</pre><br />
<br />
==== How It Works ====<br />
<br />
Lines 1-3 set the card title, the source token and the target token. Setting these tokens causes their icons/avatars to appear in the Emote section of the card.<br />
<br />
Line 4 asks the user what spell slot level they wish to use to cast magic missile. The number of missiles fired is equal to 2 plus the spell level, and this is stored in the MissileCount variable.<br />
<br />
Line 5 stores a 1 in the DisplayCount variable. This will be used to control the loop to determine the number of missiles fired and the missile number when displaying damage rolls.<br />
<br />
Line 6 initializes MissileDamage to 0<br />
<br />
Line 7 sets the left subtitle to the text "Slot Level #", where # is the spell slot level being used.<br />
<br />
Line 8 sets the right subtitle to the text "Ranged Attack".<br />
<br />
Line 9 sets the emoteText parameter with a description of the action, including the slot level and number of missiles fired.<br />
<br />
Line 10 is a label for the missile firing loop<br />
<br />
Line 11 Calls the "FireMissile" subroutine<br />
<br />
Line 12 increases the DisplayCount variable by 1<br />
<br />
Line 13 Checks to see if there are still missles to fire (DisplayCount <= MissileCount) and if so branches to MissileLoop<br />
<br />
Line 14 Displays the total damage dealt by the spell.<br />
<br />
Line 15 stops execution of the script to prevent out of context execution of the subroutine.<br />
<br />
Lines 76-21 are the FireMissile subroutine, beginning with the FireMissile label. The 1d4+1 is rolled and assigned to "ThisMissile". The result is added to the existing MissileDamage total, and a line for the current missile is displayed with the missile number and the damage for the missile.<br />
<br />
=== Longsword Attack ===<br />
<br />
This script demonstrates a standard 5E D&D melee weapon attack, including detection of misses, fumbles, hits, and critical hits. If installed, alterbars is used to decrement the target's BAR3 value by the damage dealt.<br />
<br />
[[File:ScriptCards Longsword.png|Longsword Script Output]]<br />
<br />
<pre><br />
!scriptcard {{<br />
--#title|Longsword<br />
--#leftsub|Melee Attack<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
--#emoteText|@{selected|token_name} attacks @{target|token_name}<br />
--=TargetAC|@{target|npc_ac}<br />
--?[$TargetAC.Total] -gt 0|DoneWithAC<br />
--=TargetAC|@{target|ac}<br />
--:DoneWithAC|<br />
--=AttackRoll|1d20 + @{selected|strength_mod} [STR] + @{selected|pb} [PROF]<br />
--+Attack|@{selected|token_name} rolls [$AttackRoll] vs AC [$TargetAC].<br />
--?[$AttackRoll.Base] -eq 20|Crit<br />
--?[$AttackRoll.Base] -eq 1|Fumble<br />
--?[$AttackRoll.Total] -ge [$TargetAC.Total]|Hit<br />
--+Miss|The attack missed.<br />
--^Final|<br />
<br />
--:Fumble|<br />
--+Fumble!|The attack went horribly wrong.<br />
--^Final|<br />
<br />
--:Hit|<br />
--=Damage|1d8 + @{selected|strength_mod} [STR]<br />
--+Hit!|The attack hit @{target|token_name} for [$Damage] slashing damage.<br />
--@alter|_target|@{target|token_id} _bar|3 _amount|-[$Damage]<br />
--^Final|<br />
<br />
--:Crit|<br />
--=Damage|1d8 + @{selected|strength_mod} [STR] + 1d8 [CRIT]<br />
--+Critical Hit!|The attack hit @{target|token_name} for [$Damage] slashing damage.<br />
--@alter|_target|@{target|token_id} _bar|3 _amount|-[$Damage]<br />
<br />
--:Final|<br />
}}<br />
</pre><br />
<br />
==== How it Works ====<br />
<br />
In lines 1-5, we set the title, subtitle, and emote text along with the tokens for the emote area.<br />
<br />
Lines 6-9 allow us to determine the AC of the target. On the 5E Roll20 sheet, NPCs armor class is stored in "npc_ac", while PCs armor class is in "ac". First we grab npc_ac and if it is zero, we check AC.<br />
<br />
Line 10 rolls the attack roll, rolling 1d20 and adding the attacker's strength modifier and proficiency bonus<br />
<br />
Line 11 displays the result of the attack roll on the card<br />
<br />
Lines 12-14 determine what kind of result the attack had. If the .Base value of the roll was 20, we branch to "Crit". If it was 1, we branch to "Fumble". If the .Total value of the roll was greater than or equal to the AC that was determined in Lines 6-9, we branch to Hit.<br />
<br />
Assuming we didn't branc anywhere, the result of the attack was a miss, so we display that on line 15 and then branch to "Final"<br />
<br />
This is followed by three branch segments, :Fumble, :Hit, and :Crit. A fumble displays a text message and branches to :Final.<br />
<br />
On a hit or a crit, we roll Damage (adding additional damage dice on a crit). We display a "Hit!" or "Critical Hit!" message and then make an API call to AlterBars, passing it the token id, bar we want to modify (3 in this case), and the amount we want to modify by the Damage value.<br />
<br />
=== Party Health Status ===<br />
<br />
This example calculates the current Hit Points remaining and HP percentage for each character and creates a color-coded display with the current party status.<br />
<br />
[[File:ScriptCards Party Health.png]]<br />
<br />
<pre><br />
!scriptcard {{<br />
--#title|Party Status<br />
--#titleCardBackground|#33CC33<br />
--#oddrowbackground|#bfee90<br />
--#evenrowbackground|#90eebf<br />
-->HealthCheck|@{Quej Grastra|character_id}<br />
-->HealthCheck|@{Brim Cheuto|character_id}<br />
-->HealthCheck|@{Odug Ututees|character_id}<br />
--X|End of card Execution<br />
<br />
--:HealthCheck|<br />
--=HealthPerc|[*[%1%]:hp] / [*[%1%]:hp^] * 100 \ 1<br />
--=HealthColor|000000<br />
--?[$HealthPerc.Total] -gt 50|HealthSkip<br />
--=HealthColor|FF0000<br />
--:HealthSkip|<br />
--+[*[%1%]:character_name]|has [#[$HealthColor.RollText]][*[%1%]:hp] of [*[%1%]:hp^][/#] HP [R]([$HealthPerc.Total]%)[/R]<br />
--<|End of HealthCheck<br />
}}<br />
</pre><br />
<br />
==== How it Works ====<br />
<br />
Lines 1-4, we set the card title, and set the title background and row background colors to shades of green.<br />
<br />
Lines 5-7 make gosub calls the the "HealthCheck" subroutine, passing in the character ID of each of the named characters (these are the names of the characters in my test game)<br />
<br />
Line 8 terminates the script execution.<br />
<br />
The remaining lines of the script are the HealthCheck subroutine, which works like this:<br />
<br />
Line 10 is the subroutine label (:HealthCheck)<br />
<br />
Line 11 uses the character id passed as a parameter and combines it with character attribute lookup *(...) to retrieve the value of "hp" and "hp<nowiki>^</nowiki>" for the character. The <nowiki>^</nowiki> character is used to specify that we want the MAX value for this attribute for the second call. We divide these two numbers and multiple by 100 to get a percentage. Finally, we use integer division by 1 to round the percentage and drop the decimals. The end result gets stored in the HealthPerc roll variable.<br />
<br />
Line 12 defaults to color of the health text to black<br />
<br />
Line 13 check to see if the health percentage is greater than 50. If so, it branches to HealthSkip, preventing the script from executing line 13.<br />
<br />
Line 14 sets the color of the health text to red<br />
<br />
Line 15 is the label that will be branched to from Line 13 to skip the red coloring<br />
<br />
Line 16 again uses character attribute substitution and the passed parameter value to output a display line containing the character name, the colorized health total, and the percentage value. The percentage is right-justified.<br />
<br />
Line 17 returns from the HealthCheck subroutine.<br />
<br />
=== Expanded Magic Missile Script ===<br />
<br />
This is the expanded and enhanced version of the Magic Missile script covered in {{yt|watch?v=u50xvNzS9Zk | this video}}. It includes visual and audio effects, checking and deducting spell slots, and applying damage using either Token-Mod or Alterbars.<br />
<br />
<pre><br />
!scriptcard {{ <br />
--#title|Magic Missile<br />
--#sourceToken|@{selected|token_id}<br />
--#targetToken|@{target|token_id}<br />
<br />
-->GetAndCheckSlotInformation|<br />
<br />
--=MissileCount|[$SlotLevel] + 2<br />
--=DisplayCount|1<br />
--=MissileDamage|0<br />
--#leftsub|Slot level [$SlotLevel]<br />
--#rightsub|Ranged Attack<br />
--#emoteText|@{selected|character_name} uses a level [$SlotLevel.Total] spell slot to fire [$MissileCount.Total] missiles of magical force!<br />
<br />
--:MissileLoop|<br />
-->FireMissile|<br />
--=DisplayCount|[$DisplayCount] + 1<br />
--?[$DisplayCount] -le [$MissileCount]|MissileLoop<br />
--+Total|Total damage is [$MissileDamage]<br />
-->DeductSpellSlot|<br />
--#rightsub|Level [$SlotLevel] Left: [$SlotsRemaining] <br />
-->PlayEffects|none;burst-smoke;beam-magic;spell_01<br />
-->ApplyDamageTokenmod|@{target|token_id};3;-[$MissileDamage]<br />
-->ApplyDamageAlterbars|@{target|token_id};3;-[$MissileDamage]<br />
--X|<br />
<br />
--:FireMissile|<br />
--=ThisMissile|1d4 + 1<br />
--=MissileDamage|[$MissileDamage] + [$ThisMissile]<br />
--+Missile|[$DisplayCount.Total] Hits for [$ThisMissile] [b]force[/b] damage<br />
--<|<br />
<br />
--:GetAndCheckSlotInformation|<br />
--=SlotLevel|?{Spell Slot Level?|1|2|3|4|5|6|7|8|9}<br />
--=SlotsTotal|[*S:lvl[$SlotLevel]_slots_total]<br />
--=SlotsExpended|[*S:lvl[$SlotLevel]_slots_expended]<br />
--?[$SlotsExpended.Total] -ge [$SlotsTotal.Total]|NoSlotsLeft<br />
--<|<br />
<br />
--:NoSlotsLeft|<br />
--+|[*S:character_name] has no level [$SlotLevel.Total] spell slots available.<br />
--X|<br />
<br />
--:DeductSpellSlot|<br />
--=SlotsExpended|[$SlotsExpended] + 1<br />
--@setattr|_charid [*S:character_id] _lvl[$SlotLevel]_slots_expended|[$SlotsExpended] _silent<br />
--=SlotsRemaining|[$SlotsTotal] - [$SlotsExpended]<br />
--<|<br />
<br />
--:PlayEffects|Parameters are : source effect; target effect; line effect; sound effect<br />
--vtoken|@{selected|token_id} [%1%]<br />
--vtoken|@{target|token_id} [%2%]<br />
--vbetweentokens|@{selected|token_id} @{target|token_id} [%3%]<br />
--@roll20AM|_audio,play,nomenu|[%4%]<br />
--<|<br />
<br />
--:ApplyDamageTokenmod|Parameters are tokenid;bar#;amount<br />
--@token-mod|_ignore-selected _ids [%1%] _set bar[%2%]_value|[%3%]<br />
--<|<br />
<br />
--:ApplyDamageAlterbars|<br />
--@alter|_target|[%1%] _bar|[%2%] _amount|[%3%]<br />
--<|<br />
}}<br />
</pre><br />
<br />
[[Category:Featured articles]]</div>5004103