Introduction

The PowerCards API Script allows you to create highly customizable macros that display formatted output for PC and NPC actions, spells, abilities, statistics, or almost any other purpose you can come up with. Their original purpose was to present ability and attack information (powers) in a format similar to the power blocks from the official D&D 4E products, but the format works well for any system.

PowerCards are output to the chat window with full HTML/CSS formatting. A handful of options use information from the 5E OGL sheet, but these options are not critical to the functioning of the core features of the script.

A PowerCard is created as the result of a chat string beginning with the “!power” API command, followed by a list of lines or configuration options you want to display on the card, with the whole thing enclosed in double curly brackets ({{ and }}). These lines and options are identified by tags, which always start with two dashes (--) followed by the tag name. This is followed by a vertical bar (|) and then the content of the tag. The output of the PowerCard is divided into two sections: an optional emote section that identifies the actors, describes the action, etc., and the card itself, which consists of a title block and alternately colored line sections that correspond to the tags on the card.

In general, any line that doesn’t contain a reserved tag name (see below) will be displayed as bold text followed by the tag contents. This behavior can be modified using special control characters in the tag name.

Syntax

!power {{
  --tagname|Tag Contents
  --tag2name|[[ <inline roll> ]] extra text
  --tag3name|Tag Contents
}}

Example:

!power {{ 
  --name|Melee Attack 
  --Attack|[[ 1d20 ]] vs AC 
  --Damage|[[ 1d8 ]] Slashing 
}}

Installation and Configuration

There are two options for installing PowerCards into your game:

One-Click Install As of version 3.7.2, PowerCards is now available in Roll20's One-Click API Script Install system. Simply visit the API tab for your game and type "PowerCards" in the API search window to locate the script. Click on Add Script to let Roll20 keep your PowerCards script up to date or Import to make a copy of the current version of the script.

Development GIST While PowerCards is in active development, new features and bug fixes are available first on the development GIST. In order to install the script from the development code, create a new script in your API tab and name it PowerCards.js. Visit the link above and click on the "Raw" button to open the code in a clean window. Select the code and copy/paste it into the script area in your API tab and click Save Script. Any time you wish to update to a later version, you will need to replace the script code with the latest code from the GIST.

Every few development versions, I will push the latest code to the One-Click system.

Important Clarifications

PowerCards macros are NOT scripts. There are a few things to keep in mind when developing complex powercards:

• Rolls in a PowerCard do not use Roll20's 3D dice.

• Roll IDs (results of rolls assigned to names that can be used in output as placeholders for the roll value) are NOT variables. All rolls are processed before the output portion of any PowerCard tag takes place, and Roll IDs from one roll are not available in other rolls. Roll IDs are only used to include the result of a roll in output or to compare the result in a conditional tag.

• ALL NORMAL TAGS MUST BE UNIQUE. This is true even when dealing with conditional lines. See the same name tag modifier below. Exceptions to this requirement are --template, --replacement, --replaceattrs and --replacespell tags, which are processed separately and do not create output.

• The results of a conditional line only determine if the line output is shown on the PowerCard, and does not prevent rolls in the line from being calculated and assigned to Roll IDs. This means that rolls included in a conditional line will still be processed. It is usually always a better idea to make rolls in an hroll tag and then decide what to do with them than to make a roll in a conditional line. Alternatively, use conditional inclusion on a --template tag to prevent lines from being added to the card at all.

• Selected/Target notation (i.e., @{selected|token_id} or @{target|npc_ac}) substitution happens on the chat server before PowerCards gets the command. This means PowerCard will get the VALUE of these substitutions, and not any kind of reference to what the original replacement text was. Similarly, @{} notation cannot be used in templates because the content of a template is not processed by the chat server (but parameters to templates CAN use @{} substitution).

• ANY roll that is hidden from the chat server (by being in a template, or surrounded with [#[ and ]#] instead of [[ and ]], or any other means) must use a Roll ID, or you will get a syntax error when the system tries to process the roll.

Recent Change Log

Version 3.7.2 was the first long-term version of PowerCards on the One-Click install system. Since its release, PowerCards development has continued. Newer versions of PowerCards are released on the development GIST (see the forum thread above) prior to being promoted to One-Click. Updates since the last version promotion will appear in this space.

Version 3.8.1 (Currently on the Development GIST and not available on One-Click)

• You can now use !power or !powercard or !powercards and any upper/lower case variations to call PowerCards. Previously, only "!power" was supported.
• New tag --replaceattrs creates replacement pairs for a given character_id (see below for details)
• New tag --replacespell creates replacement pairs for a spell on a character's spell list (see below for details)

Version 3.8.0

• New tag --inlinereplace allows you to define replacement sets without a handout. The format is the same as if you had added the line from a replacement handout into the card (for example, --inlinereplace|Hi|Hello;Bye|Goodbye will produce ~Hi$ and ~Bye$ replacement keys with values of Hello and Goodbye respectively. As with standard replacements, these are processed before any other part of the card, so they can be used in rolls, templates, comparisons, etc. You can use a roll query to assign the value via the chat server as well.
• You can now use [#[ and ]#] in place of [[ and ]] to prevent the chat server from processing a roll and avoid using replacement variables for [[ and ]]. In these cases, you need to use a roll ID in the roll. For example, --damage|You deal [[ [$dmg] 1d6 ]] and --damage|You deal [#[ [$dmg] 1d6 ]#] are equivalent, but the chat server won't try to process the second one.
• Multiple replacement, format, and template handouts are now available. As long as your handout name starts with "PowerCard Replacements", "PowerCard Templates", or "PowerCard Formats", the handout will be processed and cumulatively added to the appropriate list. Read order is not guaranteed, so it is best to not have duplicates between handouts.
• Consolidated code for processing handouts to speed things up a little. Not really noticeable, but worth doing anyway.
• Handout processing now strips out non-breaking spaces and paragraph starts sequences, and converts paragraph end sequences to line breaks in order to work around issues introduced by the new editor.

Version 3.7.9

• Adds the --template and --replacement tags (see sections below). This is a major new feature of PowerCards.
• Introduces some code to prevent some cases of sandbox crashes.
• Modifies the way the PowerCard Formats handout is processed to compensate for changes to the Roll20 text editor.

Version 3.7.6

• Fixed a sandbox crash that would result if the [TRKR] roll modifier was used with an invalid character ID.
• Added formatting characters to allow for the creation of HTML tables. See the formatting/tables section below for details.

Version 3.7.5

• Action list tags (--npc_action_list, etc.) now use a different method of iterating over repeating sections in the character sheet, working around a bug in the $# notation on character sheets where the order of items in a repeating section has been rearranged.

Version 3.7.4

• The --api_ tag will now process inline formatting before sending API commands. This allows the use of RollIDs in API commands, providing a way to use calculated/rolled values in API calls. It might also cause trouble for existing PowerCards using the --api_ tag if any of the inline formatting characters are used in the API string (likely uncommon, but still possible).

Version 3.7.3

• Updated the --npc_action_list and --npc_legendary_action_list tags to check for attributes attached to the character sheet in the format "action_$0_macro" and "action-l_$0_macro" with $0 being replaced by the action index. If a matching attribute exists, its value will be used as the target for the corresponding button created by the list output. If no such attribute exists, the character sheet default action will be used.
• Added the --ogl_pc_attack_list tag, which will generate a list of buttons for PC attack abilities.
• Updated all of the _list tags to use character IDs instead of the @{selected} notation so that buttons can be clicked after having deselected the token during play.
• Updated the _list and _summary tags to display a horizontal rule and title if they contain data, and to display nothing if they do not.

Using Tags

Tags are used to tell the script how to identify the Content that follows and help tell the script what to do in some cases. For example, the --name tag is used to set the name at the top of the power card. Tags ALWAYS begin with two dashes -- and a vertical bar character (|) separates the tag from its content. Everything after the vertical bar up until the next tag is encountered (specified by -- again) is considered the content of the tag.

Tag Format Examples:

 GOOD: --Tag|Content
 GOOD: --Effect|This is an effect.
 GOOD: --A Custom Tag|This is a custom tag.
 BAD: effect | This is a bad tag.
 BAD: -BadTag| This is also a bad tag.

Important Note about Replacement Notation (@{}):

The @{} notation (@{target|hp} for example) is handled by the Roll20 chat server long before PowerCards gets to process anything. This means if you use something like:

--hroll|[[ [$HPchecker] @{target|Target1|bar3} % @{target|Target1|bar3|max} * 100 + 0d0]]

PowerCars actually gets something along the lines of:

--hroll|[[ [$HPchecker] 15 % 30 * 100 + 0d0]]

It doesn't know anything about the target. All PowerCards gets are the numbers. When using a target that doesn't have the attributes referenced in the @{} notation you will receive an error (from the chat server) about the missing attributes, and PowerCards will get something along the lines of:

--hroll|[[ [$HPchecker] % * 100 + 0d0]]

Because the numeric values are empty, when PowerCards tries to process the math it will fail as well.

Tag Modifiers

A few special characters can be used in tag names to alter how the tag is displayed.

Modifier	Description
Hide Tag	Adding an exclamation mark (!) at the start of a tag will hide that tag’s name and not display it in the power card, but it will show the contents of the tag in the card. This is useful for adding blocks of text without a tag. Example: --!Tag|Content
Indent	Adding a caret mark (^) followed by a number will indent that entire line and its contents slightly. The indentation option ranges from a minimum of zero (used to reset the indent to default) to a maximum of nine, though at nine, you will not have very much room for content at all. Example: --^1Tag|Content The indent tag option can be used in conjunctions with the hidden tag option, but the exclamation mark must be first. Example || --!^1Tag|Content
Repeat	To repeat a tag and its contents, add a hash mark (#) followed by the number of times you want the content to repeat. You can also use roll queries to add a pop-up in roll20 to determine the number of times to repeat the tag when you click the macro (see second example). Example: --Damage#3|[[ 1d8 ]] slashing damage Example: --Attack#?{Number of attacks|1}|[[ 1d20 + 4 ]] Using the repeat tag will generate unique rolls for each inline roll in each repeated tag, and a card line for each iteration of the effect.
Same Name	This tag option is used to enable the use tags with the same name. Unlike repeating tags, the content is unique to each tag of the same name. To use this tag, add an asterisk * followed by a number. The number used must be unique for that instance of a tag across the whole card (So you can have --Attack*1 and --Attack*2, along with --Miss*1 and --Miss*2). Example: --Tag *1|Content Example: --Tag *2|Content
Hide Tag & Content	Add a $ in front of the tag to hide the tag and the content. This can be combined with a roll query to make this configurable on the fly. Example: --$Tag|Content Example: --?{Hit delete to show Hex damage|$}Hex:|[[1d6]] necrotic damage

Formatting and Configuration Tags

A number of tags do not actually produce a line of output. Most of these are used for specifying various format items for the card. These are listed below with their effects:

Tag	Description
--format	An option for GM's to make setting text and background colors easier. See the Format Handout section below for more detailed information. Example: --format|atwill Example: --format|encounter
--txcolor	Sets the color of the text in the title box using hex code (#000000).
--bgcolor	Sets the background color of the title box using hex code (#000000).
--erowtx	Sets the text color of even numbered rows in the body of the power card using hex code (#000000).
--erowbg	Sets the background color of even numbered rows in the body of the power card using hex code (#000000).
--orowtx	Sets the text color of odd numbered rows in the body of the power card using hex code (#000000).
--orowbg	Sets the background color of odd numbered rows in the body of the power card using hex code (#000000).
--whisper	GM would send the power card to the GM.
--titlefont	Sets the font of the title of the power card.
--subtitlefont	Sets the font of the subtitles beneath the title of the power card.
--bodyfont	Sets the font of the body of the power card. Word of caution, this absolutely will alter the font of the inline rolls as well.
--corners	Sets to roundedness of the corners of the card. Defaults to 5. Set to 0 for square corners.
--titlefontsize	Sets the size of the name of the powercard
--subtitlefontsize	Sets the size of the text of leftsub and rightsub
--bodyfontsize	Sets the size of the text in the body of the powercard
--border	Can be used to set the size style color of borders using this format: Example: --border|1px solid #000

Other Reserved Tags

There are a few other tags that have special meanings and shouldn’t be used as general tag names. These are:

Tag	Description
--charid	Gets the character_id of the character triggering the macro. Combines with --emote to create a custom look to emotes.
--emote	Creates an emote on top of the power card. Set CUSTOM_EMOTES to false in script to return to standard Roll20 orange emotes. If you have charid and emote together in the macro to use the power card styled emotes, you can put an exclamation mark in front of the emote to not show the avatar for that macro. Example: --emote|This emote would have an avatar. Example: --emote|!This emote would not have an avatar.
--emotefont	This tag will inject CSS into the emote section of the PowerCard's output. This property defaults to "font-family: Georgia, serif; font-weight: bold; " in the code and can also be specified in the PowerCard Formats handout for each format type. NOTE: At this time, you must specify either the --charid or the --tokenid tag for the --emotefont tag to take effect. Example: --emotefont|font-family: "Script"; font-weight: bold;
--name	The name of the power, skill, ability, etc. being used or whatever else you can think of. Appears at the very top of the card.
--title	Sets a tooltip on the colored title box. Useful for hiding information that would otherwise clutter the chat window.
--leftsub	Creates a smaller subtitle beneath the name of the power card, left of the diamond if used in conjunction with rightsub.
--rightsub	Creates a smaller subtitle beneath the name of the power card, right of the diamond if used in conjunction with leftsub.
--target_list	Creates a list of targets in conjunction with multiple uses of the @{target|Nth Target|token_id} roll query for each possible target. Example: --target_list|@{target|1st Target|token_id} | @{target|2nd Target|token_id} | @{target|3rd Target|token_id}
--tokenid	This tag lets you use the token image instead of character avatar for custom emotes. Must be used with either @{selected|token_id} or @{target|self|token_id}
--hroll	This tag allows you to make as many hidden rolls as needed without them showing up on the powercard. Combined with a RollID, you can reference these rolls later without showing the math. Example: !power {{--hroll|[[ [$Atk] 1d20 + 10 ]] --Attack:|[^Atk.total] or [! [^Atk.total] !] vs AC}}

Character Sheet Information Tags

A few special tags are available to extract information from NPC (or in some cases PC) character sheets when using the 5E OGL sheet. These tags create pre-formatted content areas on their own, and all require that a character id be passed as the content portion of the tag.

 Example: --npc_action_list|@{selected|character_id}

These tags are:

Tag	Description
--npc_attribute_summary	Displays a three-row list of an NPCs basic stats, including attributes (Str, Wis, etc.), Armor Class, and Challenge Rating.
--npc_qualities_summary	Displays list of any resistances, immunities, vulnerabilities and senses thant an NPC possesses.
--npc_skill_summary	Displays a list of any skills that an NPC has trained ranks in.
--npc_action_list	Shows all available “repeating NPC actions” from an NPC character sheet, along with API buttons to execute the associated actions via the character sheet interface.
--npc_legendaryaction_list	The same as npc_action_list, but pulls from the NPCs legendary action section.
--npc_reaction_list	As with the npc_action_list, this tag displays a list of NPC reactions, but because these are entered on the character sheet with just names and descriptions, they are not displayed as clickable buttons but rather the text of the reactions.
--npc_traits_list	Same as the npc_reaction_list, except that it displays items from the NPC character sheet Traits section.
--spell_slots	Works for both PCs and NPCs. Lists the available spell slots for the indicated character. If the character has no spells, nothing will be output (the whole row will be hidden). If the character does have spells, a header row will be displayed followed by a row with the total and available slots for each spell level the character has spell slots for.
--spell_list	Works for both PCs and NPCs, and outputs their spell attack bonus, their spell save DC, and clickable API buttons to cast the spells in the list.
--ogl_pc_attack_list	Displays a list of macro buttons for PC attacks using the 5E OGL Character sheet. If you define attributes on the character named "action_$X_macro", where X is the number of the attack in order on the character sheet's attack list starting at 0 (action_$0_macro, action_$1_macro, etc) the content of the attribute will be treated as a macro name that will be set on the button instead of the default sheet macro. You can also set the content to "NONE" to prevent the ability from showing in the --ogl_pc_attack_list.

As an example, the following PowerCard will display a mini character sheet for an NPC.

 !power {{
 --name|@{selected|character_name}
 --whisper|GM
 --format|badguys
 --emote|
 --tokenid|@{selected|token_id}
 --npc_attribute_summary|@{selected|character_id}
 --npc_qualities_summary|@{selected|character_id}
 --npc_skills_summary|@{selected|character_id}
 --!Actions|**Available Actions**
 --npc_action_list|@{selected|character_id}
 --!Reactions|**Available Reactions**
 --npc_reaction_list|@{selected|character_id}
 --!LA|**Legendary Actions**
 --npc_legendaryaction_list|@{selected|character_id}
 --!TR|**@{selected|character_name} Traits**
 --npc_trait_list|@{selected|character_id}
 }}

Here is an example that combines both the --spell_slots and the --spell_list tags:

 !power {{ 
 --format|bigbad
 --orowbg|#CEC7B6
 --erowbg|#CEC7B6
 --name|Spell List
 --tokenid|@{selected|token_id}
 --emote|@{selected|character_name}
 --leftsub|Atk Bonus: @{selected|spell_attack_bonus}
 --rightsub|Save DC: @{selected|spell_save_dc}
 --spell_slots|@{selected|character_id}
 --spell_list|@{selected|character_id}
 }}

Audio and Video Effects

Relatively new to the PowerCards system, these tags do not produce lines on the card but allow you to control other Roll20 systems to provide visual and audio feedback when a card is displayed or when conditions on the card are met. These tags are:

Tag	Description
--soundfx	This tag sends an api command to the Roll20 Audio Master (R20AM) script available as a one-click script install. Follow the link for more information on how to use R20AM. Example: --soundfx|_play|Bite Example: --?? $Atk >= @{target|AC} ?? soundfx *1|_play|Shortbow
--vfx_opt	This tag accepts 1, 2, or 3 parameters separated by spaces. If a single parameter is passed, it is used as the effect descriptor (eg, burst-magic) and the effect is played at the card's Token_ID token location. Example: --vfx_opt|burst-slime If two parameters are passed, the first parameter is the token who's location will be used for the effect, and the second is the descriptor. Use the format for single-location effects (burst, explosion, nova, etc). Example: --vfx_opt|@{target|token_id} glow-blood Finally, if three parameters are passed, the first is the effect starting location, the second is the effect destination location, and the third is the effect descriptor. Use this format for effects that appear between two points (beam, breath, etc). Example: --vfx_opt|@{selected|token_id} @{target|token_id} breath-fire
--audioattr	Similar to the --soundfx tag, this tag still requires the use of the Roll20 Audio Master script. This tag requires two parameters. The first is a token id, and the second is an attribute name. If the given attribute exists on the character that the token represents, it will be passed (without editing) to the !roll20AM command. For example: Example: --audioattr|@{selected|token_id} Audio_OnAttack When the PowerCard is displayed, it will check the charactersheet represented by the selected token. If Audio_OnAttack exists as an attribute, it will retrieve the value of the attribute and pass it to Roll20 Audio Master. If, for example, the Audio_OnAttack attribute for a dragon was "--play|FireBreath", the corresponding "FireBreath" sound effect track will be played (assuming you HAVE a FireBreath sound effect in your jukebox).
--vfxattr	A companion to the --audioattr tag, this new tag takes two parameters as well: a token id and an attribute name. It will check the character represented by the token for the specified attribute. If it is found, the script will interpret the contents of the tag and set up a visual effect: Example: --vfxattr|@{target|token_id} Effect_OnHit When this tag fires, it will check the targeted token for an attribute called Effect_OnHit. If it exists, it will be parsed to create a visual effect. Because @{} token references are parsed by the chat system and not the API, we can't directly specify things like @{selected|token_id} in the attribute, so instead we interpret "s" as the selected token and "t" as the target. This means the value of Effect_OnHit could be something like: s t beam-magic Which will cause a point-to-point magic beam effect starting at the selected token (s) and pointing at the target token (t). This attribute value: t glow-blood Will cause a burst of blood on the target token. PLEASE NOTE: Video effects are played on the active player page (where the Player ribbon is positioned). It is easy to forget this when testing effects on a page the players can't see.

A video explaining the Attribute based tags (--vfxattr and --audioattr) can be see here: https://www.youtube.com/watch?v=JwUkdO-F3LQ

Advanced API Usage

PowerCards supports calling the AlterBar API script, and as of version 3.7.0 also includes the ability to make “generic” API calls for any API script that can be controlled using exclamation mark commands (eg. !token-mod).

Tag	Description
--alterbar	This tag passes its content to the AlterBar script, replacing the underscore (_) character with two dashes (--).
--api_	- This special tag starts with “--api_” followed by the command to call an API script. The content of the tag is passed to the API script after replacing underscores (_) with two dashes (--). Example: --api_token-mod|_ids @{selected|token_id} _ignore-selected _set statusmarkers|blue This example calls the TokenMod API script to set the “blue dot” status marker for the selected token.

API-Specific Notes:

TokenMod : In order to call TokenMod with the --ids option, it is necessary to set token-mod's players-can-ids configuration to On with "!token-mod --configure players-can-ids|on"

Inline Rolls

The content portion of a tag can include any number of inline dice rolls. Inline rolls will not use the 3D dice system built into Roll20, but will summarize the result with a hover-over details popup window. Inline rolls are surrounded by double brackets.

   Example: --Attack|Score of [[ 1d20 ]] vs AC.
   Example: --Attack|Score of [[ 1d20 + 5 ]] vs AC.

If you place text in single brackets after a component of an inline roll, it will be displayed in the hover-over output to explain where that bonus is derived from.

   Example: --Attack|Score of [[ 1d20 [Base] + 3 [Strength] + 2 [Proficiency] ]] vs AC.

It is also possible to specify attributes from character sheets using the @{} notation. The tag below combines this with the naming of modifiers:

   Example: --Attack|[[ 1d20 + @{selected|dexterity_mod} [Dexterity] ]]

Of course, this means that a token must be selected in Roll20 before running the associated PowerCard, otherwise an error will be produced.

The results of a roll can be assigned to a RollID by including the roll name in square brackets and prefixed with a dollar sign ($) character.

   Example: --Attack|[[ [$Atk] 1d20 + @{selected|dexterity_mod} [Dexterity] ]]

The above example will store the results of the die roll in the $Atk RollID. These results can be used in other tags to check for conditions (see the Conditionals section) and their value can be displayed by using their roll id in square brackets prefixed with a carrot (^) symbol.

   Example: --Result|That [^Atk] was an impressive roll!

There are several options for modifying the way rolls are either performed or displayed. They can be added inside the opening double brackets, but must be separated by a space before and after them.

   Example: --Initiative|You rolled [[ [NH] 1d20 + 5 ]] for initiative

If multiple modifiers are desired, separate them with a vertical bar:

   Example: --Initiative|You rolled [[ [NH|TRKR] 1d20 + 5 ]] for initiative

The full list of these options are:

Roll Modifier	Description
[NH]	Disables inline roll highlighting for crit success and crit failure. This means rolls of 1 won't be highlighted in red, and the highest number on the die won't be highlighted in green.
[TRKR]	Adds an entity to the Turn Order Tracker. If the PowerCard macro does not have --tokenid or --charid, it will use the Display Name of the player that triggered the macro. If you use --charid, it will look for a token that is representing the character and use that ID, but fall back to the character name if there are no tokens representing the character.
[TXT]	Causes an inline roll to show up as text only instead of as an inline roll.
[XPND]	This inline roll option expands the roll into the full formula/expression instead of just the result. [[1d20 + @{selected|dexterity_mod} ]] becomes [(18) + 3 = 21] instead of [21]

A Note about RollIDs RollIDs are useful for two purposes: checking for results via a conditional tag (see below) and displaying their value when the card is output. RollIDs are NOT variables, and cannot be used inside other inline rolls, as inline rolls are processed as a group early on in the processing of the PowerCard and are not available when rolls are processed.

Text Formatting

The content of a tag can be formatted using the following inline formatting characters. These can be combined in any number of ways.

 **Bold**
 //Italics//
 __Underline__
 ~L, ~C, ~R aligns text in between those tags to the (L)eft, (C)enter, and (R)ight.
 ~L This text would be left aligned. ~L
 ~C This text would be centered. ~C
 ~R This text would be right aligned. ~R
 ~~~ inserts a horizontal rule.
 ^^ adds a line break
 ^*Indents the first line of a paragraph in the content of a tag. (note that this is a literal asterisk and not the level of the indent. If you wish to add additional indent levels, specify the modifier more than once. Also note that this tag needs to be at the front of the content.
 @@url@@ - Naked url, requires that ALLOW_URLS to be set to true in the script.
 @@url<nowiki>||test@@ - Hidden url, requires that ALLOW_HIDDEN_URLS to be set to true in the script. Double vertical bars (||) are required between the URL and the display text.</nowiki>
 $$#900|This text will appear in red$$ - There can be either 3 or 6 digits after the # and specify a color value in hex.

HTML Tables

With version 3.7.6, it is now possible to use the special formatting characters below to create HTML tables (HTML is stripped out of macro commands by the chat server before they are passed to PowerCards). Some important notes:

• An HTML table must be properly formatted (all open tags must be closed properly) or the display of the remainder of the card will be messed up.
• An HTML table must be contained entirely within a single PowerCards tag.

The formatting characters are:

• [TTB] and [TTE] - Correspond to the table and /table tags (Table Tag Begin and Table Tag End).
• [TRB] and [TRE] - Correspond to the tr and /tr tags (Table Row Begin and Table Row End).
• [TDB] and [TDE] - Correspond to the td and /td tags (Table Cell Begin and Table Cell End) - No, I don't know why the HTML tag for a table cell is TD instead of TC :).

CSS/HTML modifiers can be included within the formatting tags (ie, [TTB width='100%']).

Below is an example using the formatting characters to create a Shadowrun stat block (see the forum thread for a screenshot):

 !power {{
   --name|Testing
   --!Hello|~C[TTB 'width=100%' 'bgcolor=Black'][TRB][TDB align=left colspan=10]**$$#fff|Male Dwarf$$**[TDE][TRE]
   [TRB][TDB width='10%']**$$#fff|B$$**[TDE][TDB width='10%']**$$#fff|A$$**[TDE][TDB width='10%']**$$#fff|R$$**[TDE][TDB width='10%']**$$#fff|S$$**[TDE][TDB width='10%']**$$#fff|W$$**[TDE][TDB width='10%']**$$#fff|L$$**[TDE][TDB width='10%']**$$#fff|I$$**[TDE][TDB width='10%']**$$#fff|C$$**[TDE][TDB width='10%']**$$#fff|EDG$$**[TDE][TDB width='10%']**$$#fff|ESS$$**[TDE][TRE]
   [TRB 'bgcolor=#444444'][TDB width='10%']**$$#fff|5(6)$$**[TDE][TDB width='10%']**$$#fff|4$$**[TDE][TDB width='10%']**$$#fff|4(5)$$**[TDE][TDB width='10%']**$$#fff|6$$**[TDE][TDB width='10%']**$$#fff|6$$**[TDE][TDB width='10%']**$$#fff|5$$**[TDE][TDB width='10%']**$$#fff|5$$**[TDE][TDB width='10%']**$$#fff|3$$**[TDE][TDB width='10%']**$$#fff|2$$**[TDE][TDB width='10%']**$$#fff|4.3$$**[TDE][TRE][TTE]~C
 }}

The Format Handout

The --format tag allows you to specify pre-defined sets of tags used for configuring the look of your PowerCards, such as fonts, background colors, row colors, and the like. The GM of the campaign must create a handout and name it exactly “PowerCard Formats” (Case sensitive) so that the script can find the information and parse the formatting info as needed. The text of this handout consists of a list or format names, a colon (:) and their associated tags, separated by linebreaks. For example:

  atwill: --txcolor|#000000 --bgcolor|#004400
  tracy: --txcolor|#000000 --bgcolor|#008800 --titlefontshadow|none
  bigbad: --txcolor|#ffff00 --bgcolor|#000000 --titlefontshadow|#0000cc --corners|10

Each format can then be referenced in a PowerCard using the --format tag.

  Example: --format|bigbad

This example will create yellow text on a black background for the title of the card, set the color of the title font shadow effect to a shade of blue, and set the corner roundness to 10.

If players will be creating their own PowerCard macros, the “PowerCard Formats” handout should be viewable by all players so they can see the list of available formats.

Target Info Charms

This feature lets you retrieve information about character sheet attributes from one or more targets and display this information in the content of the tag. Token charms are surrounded by double-percent signs (%%), and have a few requirements:

• You MUST specify a --target_list tag, even if there is only a single target.

• If a tag uses a charm, that target is “consumed” for the purposes of further charm use in the PowerCard. In other words, the first tag to use a charm references the first target in the target list, and is the ONLY tag that will be able to reference that target (with charms). The second tag containing charms uses the next target, etc. If you need multiple lines, insert line break characters (^^) into the content.

• Charm names are case sensitive, so AC, ac, Ac, and aC are all different names.

 Example: !power {{ 
 --name|Single Target Attack --target_list|@{target| |token_id} 
 --Attack|[[1d20+5]] | [[1d20+5]] vs %%AC%% Armor Class (%%token_name%%) --Hit|[[1d8+3]] slashing damage }}

 Example: !power {{ 
 --name|Scorching Burst | Nine Targets 
 --target_list|@{target|1st|token_id} | @{target|2nd|token_id} | @{target|3rd|token_id} | @{target|4th|token_id} | @{target|5th|token_id} | @{target|6th|token_id} | @{target|7th|token_id} | @{target|8th|token_id} | @{target|9th|token_id} 
 --Attack#?{Number of targets|1}|[[1d20+5]] vs %%Reflex%% Reflex (%%token_name%%) 
 --Hit|[[1d8+3]] fire damage 
 }}

This last example requires a bit more explanation. For a multi-attack power like Scorching Burst in D&D 4e, you create the macro as above and just click nine times and then when the pop up for number of targets appears, type in the actual number of targets in the area and hit enter. The script will ignore the rest of the targets in the list.

   Example: !power {{ --name|Stats --target_list|@{target|1st Target|token_id} --Target|%%token_name%% ^^ **Hit Points:** %%bar3%%/%%bar3_max%% ^^ **Defenses:** AC %%AC%%, Fort %%Fortitude%%, Reflex %%Reflex%%, Will %%Will%% }}

Here, we are pulling several different charms from the target, but want them on separate lines, so linebreaks are inserted, along with names for the lines. Any character attribute can be retrieved with a token charm (ex, %%Strength%%), and there are a few special-case charms.:

   %%token_name%%
   %%bar1%%
   %%bar1_max%%
   %%bar2%%
   %%bar2_max%%
   %%bar3%%
   %%bar3_max%%
   %%who%% - gets the DisplayName of whomever triggered the macro/powercard

Conditionals

Conditionals are simple logic using either the base value of a die roll or the total value of the entire inline roll. They can only be used at the start of a tag and their result (true or false) will determine if the tag is displayed on the card.

Conditionals are used by wrapping them in double question marks (??) at the start of a tag, telling the script which roll to use, whether to use the base value or total, how to compare it, and to what to compare it to.

For example... a basic crit macro for a D&D melee attack with a long sword:

 !power {{
 --name|Basic Attack
 --leftsub|Longsword
 --rightsub|Range Melee
 --Attack:|[[ [$Atk] 1d20 + 4 [Str Mod] + 3 [Weapon Proficiency] ]] vs AC
 --Hit:|[[ 1d8 + 4 [Str Mod] ]] slashing damage
 --?? $Atk.base == 20 ?? Critical Hit:| Add [[1d8]] slashing damage
 }}

Conditionals are structured in the format:

 ?? LeftValue OPERAND RightValue ??

LeftValue and RightValue can be a number, a roll id ($Roll), or a roll query ( ?{target|AC} ), or even an attribute reference ( @{selected|attribute} ). OPERAND can be one of the following:

 <, <=, ==, >=, >, <> (not equal), % (evenly divisible), ~% (not evenly divisible)

Very important!! You must have a space between each part of the conditional. No spaces will cause an undefined variable crash.

Conditionals can also be extended to test for multiple values using AND and OR to separate conditions, but the conditional will stop processing conditions as soon as it has identified a condition that will override anything else it finds. This means, for example, that multiple conditions separated by AND will stop evaluating conditions as soon as it finds a value of FALSE for any condition. Here is an example of an extended conditional with complex logic for a D&D 5e melee attack:

 !power {{
 --name|Basic Attack
 --leftsub|Longsword
 --rightsub|Range Melee
 --Attack:|[[ [$Atk] 1d20 + 3 [Str Mod] + 2 [Proficiency] ]] vs AC
 --?? $Atk.base == 1 OR $Atk.total < @{target|AC}?? !Miss:|You missed.
 --?? $Atk.total >= @{target|npc_ac} AND $Atk.base <> 1 AND $Atk.base <> 20 ?? Hit:|[[1d8 + 3]] slashing damage
 --?? $Atk.base == 20 ?? Critical Hit:|[[2d8 + 3]] slashing damage
 }}

Conditionals can also be repeated, resulting in multiple actions based on the same criteria being met. The following example expands on the previous attack by optionally playing a sound if the attack critically hits.

 !power {{
 --name|Basic Attack
 --leftsub|Longsword
 --rightsub|Range Melee
 --Attack:|[[ [$Atk] 1d20 + 3 [Str Mod] + 2 [Proficiency] ]] vs AC
 --?? $Atk.base == 1 OR $Atk.total < @{target|AC}?? !Miss:|You missed.
 --?? $Atk.total >= @{target|npc_ac} AND $Atk.base <> 1 AND $Atk.base <> 20 ?? Hit:|[[1d8 + 3]] slashing damage
 --?? $Atk.base == 20 ?? Critical Hit:|[[2d8 + 3]] slashing damage
 --?? $Atk.base == 20 ?? soundfx:|_play|HeadShot
 }}

Templates

Note: This section of the PowerCards Wiki entry is still being developed. It will end abruptly, contain errors, etc :)

Note: Templates are a feature added in 3.7.9, which is currently pending a pull request to the repository. It should be available on or after 7/10/2018.

Note: The examples in this section are simplified to illustrate concepts. Real templates will likely be much more complex.

There is a YouTube video on Templates and Replacements available here : https://www.youtube.com/watch?v=ESfovaVMddw

The template system is a major new addition to PowerCards. It allows you to define templates in a handout and then use those templates in PowerCard macros. The --template tag is used to import a template, which can use any number of parameters. Parameters are specified by a tilde (~) character, followed by the parameter number (starting a 0) and ending with an exclamation point (!). So the first parameter passed to the template is ~0!, the second is ~1!, and so on.

Here is an example template that uses six parameters (~0! thru ~5!):

weapon:--name|~0! --leftsub|~1! --rightsub|~2! --Attack:|[[ [$Atk] ~3! ]] vs AC ~4! --Damage:|[[ [$Dmg] ~5! ]]

Important Notes about Template Syntax

• @{} notation (such as @{selected|character_name} can't be used in a template - this notation is processed by the chat server before the result is passed to PowerCards. This notation CAN be used when calling the template and passing parameters, however.
• Any inline roll included in a template that would not be valid at chat-time must use a roll id, otherwise the chat server will return an error.

In order to call this template from a PowerCard macro, we would use the --template tag and supply the parameters, separated by semicolons:

!power {{
  --template|weapon|Longsword;Melee Attack; 5 ft. Reach;2d20kh1;@{target|AC};1d8+@{selected|strength_mod}
}}

When processed, this will be identical to writing out the card as:

!power {{
  --name|Longsword
  --leftsub|Melee Attack
  --rightsub|5 ft. Reach
  --Attack:|[[ [$Atk] 2d20kh1 ]] vs AC @{target|AC}
  --Damage:|[[ [$Dmg] 1d8 + @{selected|strength_mod} ]]
}}

Templates can also support optional line inclusion. If a tag is prefixed by a condition in square brackets, the condition will be evaluated to determine if the line should be included by the template based on the following rules:

• If the condition is evaluatable as a javascript expression, the expression will be evaluated. If true, the line will be included. If false, it will be excluded.
• If the condition is NOT an evaluatable javascript expression, the line will will be included if it is not empty. If it is empty (as in [] as the prefix) the line will be excluded.

It is also important to note that template conditions are evaluated at the point the templates are added to the card - no rolls have been evaluated at this point, so the result of roll IDs can't be used here.

Here is an example of a template with optional lines:

weapon:--name|~0! --leftsub|~1! --rightsub|~2! --Attack:|[[ [$Atk] ~3! ]] vs AC ~4! --Damage:|[[ [$Dmg] ~5! ]] --["~0!"=="Flaming Sword"]Flames:|On a hit, the victim takes [[ [$Flame] 1d8 ]] fire damage

In this case, if we were to use the same macro that we used above to execute the template, nothing would change. However, if we used:

!power {{
  --template|weapon|Flaming Sword;Melee Attack; 5 ft. Reach;2d20kh1;@{target|AC};1d8+@{selected|strength_mod}
}}

The additional "Flames: On a hit..." line would be added to the card.

A macro can contain any number of --template lines, but they should specify different templates to include, as specifying the same template more than once will include duplicate tag names, which is not allowed with PowerCards. Because the --template tag itself is removed when the template is expanded, there is no need to use same-name modifiers (*1, *2, etc) with the --template tag.

When a macro contains multiple templates, they will be included with their order and location within the card preserved.

Replacement Values

Note: This section of the PowerCards Wiki entry is still being developed. It will end abruptly, contain errors, etc :)

Note: Any roll that is part of a PowerCard that contains replacements MUST use a Roll ID, and should be hidden from the chat server by using [#[ and ]#] instead of the normal [[ and ]] that surround an inline roll.

There is a YouTube video on Templates and Replacements available here : https://www.youtube.com/watch?v=JwUkdO-F3LQ

Replacement values allow you to specify a number of key/value pairs that will be replaced in a PowerCard. Replacement lists are established by creating a handout called "PowerCard Replacements" and entering replacement sets on named lines. Each set begins with a set name, followed by a colon, followed by a list of key/value pairs. The keys are separated from the values with a vertical bar (|) character, and the pairs are separated from each other with a semi-colon (;).

An example replacement handout:

Light Crossbow:AttackName|Light Crossbow;AType|DEX;DType|piercing;BaseDamage|1d8;CritDamage|2d8;HitBonus|;ADesc|
Longbow:AttackName|Longbow;AType|DEX;DType|piercing;BaseDamage|1d8;CritDamage|2d8;HitBonus|;ADesc|
Longsword:AttackName|Longsword;AType|STR;DType|slashing;BaseDamage|1d8;CritDamage|2d8;HitBonus|;ADesc|
Mace:AttackName|Mace;AType|STR;DType|bludgeoning;BaseDamage|1d6;CritDamage|2d6;HitBonus|;ADesc|

In the case above, there are four replacement sets defined: Light Crossbow, Longbow, Longsword, and Mace. Each of these sets defines replacement keys for AttackName, AType, DType, BaseDamage, CritDamage, HitBonus, and ADesc.

In a macro, the --replacement can be used to include the values of one of these replacement sets. Then, the macro can use these replacement keys by enclosing their names in ~ and $ characters (~AttackName$) for example. Consider the following simplified macro:

!power {{
--replacement|Longsword
--name|~AttackName$ Attack
--Damage|On a hit, the ~AttackName$ deals [[ [$Dmg] ~BaseDamage$ ]] ~DType$ damage.
--Crit|On a critical hit, the ~AttackName$ deals [[ [$Crit] ~CritDamage$ ]] ~DType$ damage.
}}

This will output a card displaying "Longsword Attack" as the name of the card, and showing damage values for 1d8 and 2d8 for hit and crit damage, along with "slashing" as the damage type.

If the Longsword value is replaced:

!power {{
--replacement|Mace
--name|~AttackName$ Attack
--Damage|On a hit, the ~AttackName$ deals [[ [$Dmg] ~BaseDamage$ ]] ~DType$ damage.
--Crit|On a critical hit, the ~AttackName$ deals [[ [$Crit] ~CritDamage$ ]] ~DType$ damage.
}}

The card with display "Mace Attack" as the name of the card, use 1d6/2d6 for the dice rolls, and display "bludgeoning" as the damage type.

Multiple replacement sets can be specified on a single --replacement tag line by separating the sets with a semi-colon (;) character. If these replacement sets define the same keys, the value for any particular key will be the last one processed by the card. (so if --replacement|Longsword,Longbow is used, the values for Longbow will override the values for Longsword).

(NOTE: Information about combining Replacements and Templates is being written)

Inline Replacements

A specialized variation of the Replacements feature detailed above, inline replacements (--inlinereplace) allow you to define replacements directly in a macro.

 --inlinereplace|NAME|@{selected|character_name};AC|@{target|AC}

The line above would create two replacement keys (~NAME$ and ~AC$) with their corresponding values. Just like normal replacements, these are processed before any other parts of the card are examined, so the replacement values can be used in templates and normal tags.

Attribute Replacements

NOTE: Attribute Replacement is an in-development feature for PowerCards 3.8.1, and is currently not available on the One-Click Install version.

NOTE: Attribute Replacements current assumes you are utilizing the 5E OGL Character Sheet

Another type of specialized replacement, attribute replacements take a prefix and a character ID:

 --replaceattrs|S-|@{selected|character_id}
 --replaceattrs|T-|@{target|character_id}
 --replaceattrs|FRED-|@{Fred|character_id}

Would create three series of replacement pairs, one starting with S-, one with T- and one with FRED-. The following attributes will be extracted from the character and loaded as replacement values:

  CN - Character Name
  CID - Character ID
  PB - Proficiency Bonus
  STR - Strength score
  MSTR - Strength modifier
  INT - Intelligence score
  MINT - Intelligence modifier
  WIS - Wisdom score
  MWIS - Wisdom modifier
  CON - Constitution score
  MCON - Constitution modifier
  DEX - Dexterity score
  MDEX - Dexterity modifier
  CHA - Charisma score
  MCHA - Charisma modifier
  SBSTR - strength_save_bonus
  SBINT - intelligence_save_bonus
  SBWIS - wisdom_save_bonus
  SBCON - constitution_save_bonus
  SBDEX - dexterity_save_bonus
  SBCHA - charisma_save_bonus
  SAB - Spell Attack Bonus
  SSDC - Spell Save DC
  SAM - Spellcasting ability modifier (just the number)
  R - Race
  C - Class
  L - Level
  AC - Armor class. Will use the "ac" attribute for non-NPCs and the "npc_ac" attribute for NPCs.
  SSL#T - (S)pell (S)lots (L)evel # (T)otal (ie, SSL1T, SSL7T, etc)
  SSL#E - (S)pell (S)lots (L)evel # (E)xpended (ie, SSL1E, SSL7E, etc)

Each of these replacement values would then be available for preceded by the prefix defined in the --replaceattrs tag. For example, using the tags above, ~S-MWIS$ would be replaced with the selected character's Wisdom Modifier, while ~T-SSDC$ would be replaced with the target's Spell Save DC.

Spell Replacements

Note: Spell replacements if a feature in development in version 3.8.1 of PowerCards. It is not currently available on the One Click install system.

Yet another specialized replacement function, spell replacements require a character ID and a spell name, and will create a number of replacement keys based on the information for the spell retrieved from the given character sheet.

 --replacespell|@{selected|character_id}|Guiding Bolt

The above will cause PowerCards to search the indicated character sheet for a spell named Guiding Bolt. If found, a number of replacement pairs will be created:

   SP-NAME - Spell Name
   SP-LEVEL - Spell level
   SP-SCHOOL - Spell school
   SP-RANGE - Spell range
   SP-DURATION - Spell duration
   SP-ATTACK - either "Ranged", "Melee" or "None"
   SP-DAMAGE - Primary damage dice count
   SP-DAMAGETYPE - Primary damage dice type
   SP-DAMAGE2 - Secondary damage dice count
   SP-DAMAGETYPE2 - Secondary damage dice type
   SP-HLDIE - Number of dice added per higher level slot used.
   SP-HLDIETYPE - Dice type added at higher levels
   SP-OUTPUT - Spell output type (ATTACK or SPELLCARD)
   SP-DESCRIPTION - Spell description
   SP-ATHIGHER - Descriptive text of effect at higher levels.
   SP-ADDABILITY - 1 if the character's spellcasting ability modifier should be added to damage. 0 if not.
   SP-SAVE - Ability that the spell can be saved against (ie, Dexterity, Wisdom, etc)
   SP-SAVESUCCES - What happens on a successful save
   SP-HEALING - Amount of healing done by the spell
   SP-CASTINGTIME - Casting time for the spell

It would also be possible to create a character that is essentially a spell book, giving them the spells you player's/NPCs have access to and putting their character ID (or an @{} reference to it) in the macro, meaning characters would not need the spells set up on their own character sheets.

Template and Replacement Library

As the template system evolves and script users develop templates for various systems, I will collect them here for the community to use.

Note: this section of the wiki is under development

Below are some examples I use for my game using the 5E OGL character sheet:

Card Basics Template

Basics:--tokenid|~0! --target_list|~1! --emote|~S-CN$ ~2! against ~T-CN$ --format|~S-CN$ --name|~3! --leftsub|~4! --rightsub|~5!

Requires v3.8.1 or higher. Requires a --replaceattrs tag with S- and the selected character ID, and a --replaceattrs tag with T- and the target character ID. This template takes 6 parameters:

1. Active/Selected Character Token ID
2. Target Character Token ID
3. Action being performed by Selected Character
4. Name/Header of the PowerCard
5. Text for the left side subtitle
6. Text for the right side subtitle

Contributors

The following members of the Roll20 community have greatly aided with the creation and enhancement of this script either through their scripting expertise or their suggestions to improve features of the script and their relentless bug hunts!

 Sky – The original author of the script
 Alex L.
 Brian
 Chris N.
 Rob J.
 The Aaron
 GenKitty
 Sean G
 Janick H.