Latest revision as of 13:46, 31 March 2022

Page Updated:   2022-03-31

PowerCards is an API script meant to show character stats, attributes & more in a consistently formatted blocks in the q Text Chat, independently from Character Sheet's Roll Templates.

See Also: ScriptCards, a new API by PowerCards' maintainer, rewritten from the ground up to have more features and easier to improve.

Check out the latest forum thread: Script: PowerCards 3 (Thread 6)

PowerCards Macro Helper is a useful companion API for PowerCards.

Example of PowerCards from the PowerCards: Templates and Replacements-introduction video

[edit] Introduction

The API script allows you to generate a summary display of an ability, spell, creature, or whatever you wish to build via a series of tags and content for those tags.

Tag: In PowerCards, a Tag is a line of output on a displayed card. Each Tag is uniquely named and, by default, will display the name of the tag followed by the value of its content.

With Version 3.8.11 (2019-02-19), a new ancillary addon API called PowerCards Macro Helper was also made, which automates PowerCard creation for games using the D&D 5E by Roll20-character sheet.

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

Beginning with version 3.7.0(early 2018) of PowerCards, (Kurt J.) have taken over maintaining, updating, and expanding PowerCards. Over time, additional features have been added, and an ongoing quest is underway to lock down any outstanding issues that may cause sandbox crashes or other undesirable behavior.

[edit] Installation and Configuration

There are two options for installing PowerCards into your game:

1. One-Click Install Since 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.

2. 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, Kurt J. will push the latest code to the One-Click system.

[edit] Anatomy of a PowerCard Macro

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.

By default, PowerCards will use a white background with black text and a white dropshadow for titles, and alternating rows of dark (#B6AB91) and light (#CEC7B6) brown backgrounds with black text for tag rows. These colors can be changed by specifying either a format tag or the individual txcolor, bgcolor (both for the title portion of the card), erowtx, erowbg, orowtx and orowbg tag. e is for even rows, o is for odd rows, tx refers to "text color", and bg is "background color". These tags take a single hex color specification.

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.

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

Note: Some variable have ogl in them, and it refers to the old name that the D&D 5E by Roll20 character sheet was known as (5E OGL sheet).

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

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

PowerCards 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.

[edit] 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. Note: As of version 3.8.3, using a RollID in a repeat tag will append _# to the RollID, where # is the iteration of the repetition. For example, --Attack#3|Fred rolls [[ [$atk] 1d20 ]] will result in three RollIDs called atk_1, atk_2, and atk_3 containing the results of each roll.
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

[edit] Formatting and Configuration Tags

A number of tags do not actually produce a line of output. These formatting and configuration tags cannot be part of a conditional. 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

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

[edit] 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 D&D 5E by Roll20 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_skills_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. If you define an attribute on the character sheet with the name "action_$X_macro" - where X is replaced with the zero-based action number - and set its value to a macro (include the #) this tag will use the given macro as the action for the button produced instead of the sheet default action.
--npc_legendaryaction_list	The same as npc_action_list, but pulls from the NPCs legendary action section. If you define an attribute on the character sheet with the name "action-l_$X_macro" - where X is replaced with the zero-based action number - and set its value to a macro (include the #) this tag will use the given macro as the action for the button produced instead of the sheet default action.
--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_trait_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. (As of version 3.8.3: If you define attributes on the character named "spell_spellname_macro" (replacing spellname with the name of the spell exactly as it is on the character sheet, but replacing spaces with underscores) and specify a macro as the value of the attribute (such as #GuidingBolt) that macro will be used in place of the default character sheet macro for the spell.)
--ogl_pc_attack_list	Displays a list of macro buttons for PC attacks using the D&D 5E by Roll20 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. The specified macro should include the # sign (ie, #SwordAttack). 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}
 }}

[edit] 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|_audio,play,nomenu|Bite Example: --?? $Atk >= @{target|AC} ?? soundfx *1|_audio,play,nomenu|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): Roll20 PowerCards - Attribute-based Video and Audio Tags(YouTube) - a 15min video by Kurt Jaegers showing the tags for v3.7.1 (April, 2018)

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

Referencing RollIDs RollIDs are stored in memory and can be used for text output or for conditionals. There are several different options for checking the value of a RollID. Given a RollID called $Roll, the following values are available:

RollID + Modifier	Description
$Roll.base	The value of the dice rolled for the roll, without any static modifiers included
$Roll.total	The total value of the dice and modifiers of the roll. This is the default for simply $Roll as well.
$Roll.ss	The number of successes for rolls that include a target number (i.e., for a roll of "3d6>3", $Roll.ss would return the number of dice that rolled a 4, 5, or 6)
$Roll.ones	The number of dice that rolled a one.
$Roll.tens	The number of dice that rolled a ten.
$Roll.aces	The number of dice that rolled the highest number on the die. (DEVELOPMENT VERSION ONLY - not yet on OneClick)
$Roll.odds	The number of dice that rolled an odd number. (DEVELOPMENT VERSION ONLY - not yet on OneClick)
$Roll.evens	The number of dice that rolled an even number. (DEVELOPMENT VERSION ONLY - not yet on OneClick)
$Roll.halfbase	One half of the $Roll.base value (rounded down)
$Roll.halftotal	One half of the $Roll.total value (rounded down)

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.

[edit] Formatting

Info on how to style and format your PowerCards.

[edit] 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
 [! and !] surrounding text will format the contained text as an inline roll 
 ^*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||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.
 $$#900|This text will appear in red$$ - There can be either 3 or 6 digits after the # and specify a color value in hex.

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

 !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
 }}

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

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

[edit] Conditionals

Note: Conditionals evaluate from left to right with no order of operations respected. An AND preceded by a false condition will make the whole conditional false, while and OR preceded by true condition will make the whole condition true. If you need more complicated conditions that respect order of operations, consider using Expanded Conditionals (see below).

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
 }}

Checking against the results of a RollID supports several modifiers in addition to .base and .total. These are:

RollID + Modifier	Description
$Roll.base	The value of the dice rolled for the roll, without any static modifiers included
$Roll.total	The total value of the dice and modifiers of the roll. This is the default for simply $Roll as well.
$Roll.ss	The number of successes for rolls that include a target number (i.e., for a roll of "3d6>3", $Roll.ss would return the number of dice that rolled a 4, 5, or 6)
$Roll.ones	The number of dice that rolled a one.
$Roll.tens	The number of dice that rolled a ten.
$Roll.halfbase	One half of the $Roll.base value (rounded down)
$Roll.halftotal	One half of the $Roll.total value (rounded down)

[edit] Expanded Conditionals

Note: Unlike normal conditionals, Expanded Conditionals will follow the Javascript Order of Operations and will be fully evaluated before rendering a true/false verdict

New in version 3.8.4 (and updated in 3.8.5), expanded conditionals allow for some additional functionality when using conditional tag prefixes.

Expanded conditionals are surrounded by ?! and !? markers, and PowerCards will attempt to determine if the text within the conditional markers is true or not. As with normal conditionals, everything must be separated from everything else with spaces so the script can process the various pieces.

There are a number of characters that are not permitted in expanded conditionals. These are:

= ; < > ! { } [ ] ( ) . & |

Instead of using these characters as operators, the following text-based operators are available:

-eq is equivalent to ==
-ne is equivalent to !==
-gt is equivalent to >
-lt is equivalent to <
-ge is equivalent to >=
-le is equivalent to <=
-and is equivalent to &&
-or is equivalent to ||

Example:

--?! $atk % 10 -eq 1 !?Ones|The roll ends in a 1

The above conditional takes the vaule of $atk and divides it by 10. If the remainder of the division is 1, the conditional is true. This would be true for values of 1, 11, 21, 31, etc.

Currently because of character restrictions (inability to use the "." character), it is not possible to reference the .base, .successes, or .total value of roll IDs (the total is always returned right now). An alternative method for specifying these modifiers is being developed for 3.8.6.

[edit] Else Conditionals

Introduced with update 3.8.13, Else Conditionals introduce a new method for testing values in your cards. An "else" conditional must be preceded by a standard/extended conditional statement and can only be true if the preceding statement(s) are false. When using standard (?? .. ??) conditionals, the else conditional is ?+ .. +?. When using extended conditionals (?! .. !?) the else conditional is ?- .. -?.

Example:

The "standard" D&D 5E attack card checks to see if you hit, crit, miss, or fumble, and includes lots of checks to see what result should actually be displayed:

!power {{
--name|5E Attack
--hroll|[[ [$ac] 1d6+10 ]] [[ [$dmgBase] 1d8 + 5 ]] [[ [$dmgCrit] 2d8 + 5 ]]
--Attack|You attack, rolling [[ [$atk] 1d20 + 5 [STR] + 3 [PROF] ]] vs AC [! [^ac] !]
--?? $atk.base == 20 ?? Critical Hit!|You strike a vital spot for [! [^dmgCrit] !] damage!
--?? $atk.total >= $ac AND $atk.base <> 20 AND $atk.base <> 1 ?? Hit!|Your blow lands for [! [^dmgBase] !] damage!
--?? $atk.total < $ac AND $atk.base <> 20 AND $atk.base <> 1 ?? Miss|Your attack missed!
--?? $atk.base == 1 ?? Fumble|Your attack went horribly wrong!
}}

Notice all of the "AND" logic and repetition because each line doesn't know the result of the line before it. With "else conditionals" (and a little reordering of the lines) we can simplify this type of card and make what is happening much clearer. The Else conditional should be read as "If nothing above me was true, and the following conditions are true...":

!power {{
--name|5E Attack
--hroll|[[ [$ac] 1d6+10 ]] [[ [$dmgBase] 1d8 + 5 ]] [[ [$dmgCrit] 2d8 + 5 ]]
--Attack|You attack, rolling [[ [$atk] 1d20 + 5 [STR] + 3 [PROF] ]] vs AC [! [^ac] !]
--?? $atk.base == 20 ?? Critical Hit!|You strike a vital spot for [! [^dmgCrit] !] damage!
--?+ $atk.base == 1 +? Miss *1|Your attack missed, and if you play with fumbles, you fumbled!
--?+ $atk.total >= $ac +? Hit|Your blow lands for [! [^dmgBase] !] damage!
--?+ 1 == 1 +? Miss *2|Your attack missed
}}

To begin a new "If ... then ... Else ..." style chain, just use a new standard/expanded conditional (?? or ?!).

Note: Standard and Expanded conditionals are processed separately and the true/false value of one type does not carry over to the other type of conditional.

[edit] SkipTo and Labels

Version 3.8.14 introduces two new types of tags that allow a measure of flow control over your PowerCards.

SkipTos begin with "skipto" (case insensitive) and follow the required uniqueness rule (so use skipto*1, skipto*2, etc) and will instruct PowerCards to skip card lines until the matching label is hit. The label is specified as the content of the tag. For example:

--skipTo|EndOfCard

will hide all additional card lines until it finds a label called "EndOfCard" (If no matching label is found, the rest of the card will be hidden.)

Labels begin with a colon (:) and are not added to card output (though they must still be unique, and as with all non-visible tags any inline rolls will still be executed and assigned to rollids. The | separating content MUST be included, and the content can be treated as a comment of sorts because it won't be shown on the card. The corresponding label for the skipto above would be:

--:EndOfCard|

Note that skipto and label names are not case sensitive.

Example:

!power {{ 
  --name|5E Attack
  --Attack Roll|You roll [[ [$atk] 1d20 + @{selected|strength_mod} + @{selected|pb} ]] vs AC [! @{target|npc_ac} !]
  --?? $atk.base == 20 ?? skipto*1|Critical
  --?? $atk.base == 1 ?? skipto*2|Fumble
  --?? $atk.total >= @{target|npc_ac} ?? skipto*3|Hit
  
  --:Miss| Since we didn't skip to anywhere else, assume a miss
  --Miss|Your attack missed.
  --skipto*4|EndOfCard

  --:Fumble|
  --Fumble|You miss horribly!
  --Extra Fumble Stuff|Maybe a roll on a fumble table?
  --skipto*5|EndOfCard

  --:Hit|
  --Hit!|Your attack hit for [[ 1d8 + @{selected|strength_mod} ]] damage!
  --Extra Hit Stuff|Who knows? Could be anything!
  --skipto*6|EndOfCard

  --:Critical|
  --Critical Hit|You strike a decisive blow for [[ 2d8 + @{selected|strength_mod} ]] damage!
   --Extra Crit Stuff|Extra stuff that might happen on a crit!

  --:EndOfCard|
}}

In the example above, SkipTo is used to break the card into more readable sections and reduce the number of conditionals needed to perform this kind of card while taking into account rolling a critical, a miss, or a fumble.

[edit] Templates

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

PowerCards : Templates and Replacements (YouTube) - a 35min introduction to the --template and --replacement-tags by Kurt Jaegers (Jun 24, 2018)

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.

'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.

Example: 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.

[edit] Combining Templates and Replacements

When used together, Templates and Replacements can produce very flexible cards. Templates can directly use replacement values in the template text, or they can be passed as parameters. Using values directly in the template text allows you to use features like optional tag inclusion.

When a card is processed, all replacement pairs are resolved first (including --replacement<code>, <code>--replaceattrs, --replacespell, and --inlinereplace). Next, all templates are processed, including the substitution of replacement values in both tags and content of each template like. Finally, the resulting card is processed with the final template and replacement values in place as if they had been directly entered onto the card.

Note: This section of the Wiki is still in development

[edit] Replacements

[edit] Replacement Values

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=ESfovaVMddw

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).

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

[edit] Repeating Section Replacements

Note: While the examples in this section utilize the D&D 5E by Roll20 sheet, the --replacesection-tag is designed to support any sheet that uses repeating sections

A repeating section replacement (--replacesection tag) will match an entry in a repeating section for your character sheet and create replacement pairs for every attribute associated with that entry. This is a more generic version of the other replacement functions below, and allows for support of any character sheet that uses repeating sections. You will need to refer to the documentation for your character sheet for what repeating sections are available, how to match them, and the names of the various attributes that comprise them.

While the various [[5E OGL]]-related tags do some processing to make the returned results more usable, the --replacesection-tag will simply return the raw replacement set.

Note that all of the parameter values are case sensitive.

--replacesection|character_id|entryname|sectionname|searchtext|replacementprefix

Example:

--replacesection|@{selected|character_id}|Warhammer|attack|atkname|PCA-

This tag will search for repeating_attack_$* entries on @{selected|character_id}. It will check the attribute called repeating_action_$*_atkname for entries matching Warhammer. If found, a replacement set will be created with each pair prefixed with PCA-

For the D&D 5E by Roll20 sheet, the following replacement pairs are created by the above command:

PCA-options-flag
PCA-options-flag_max
PCA-itemid
PCA-itemid_max
PCA-atkname
PCA-atkname_max|
PCA-dmgbase
PCA-dmgbase_max
PCA-dmgtype
PCA-dmgtype_max
PCA-dmg2base
PCA-dmg2base_max
PCA-dmg2attr
PCA-dmg2attr_max
PCA-dmg2flag
PCA-dmg2flag_max
PCA-atkattr_base
PCA-atkattr_base_max
PCA-dmgattr
PCA-dmgattr_max
PCA-rollbase_dmg
PCA-rollbase_dmg_max
PCA-rollbase_crit
PCA-rollbase_crit_max
PCA-atkbonus
PCA-atkbonus_max
PCA-atkdmgtype
PCA-atkdmgtype_max
PCA-rollbase
PCA-rollbase_max

Please note that in some cases, the values of these attributes may not be all that useful in a PowerCard (nearly all of the *_max attributes are empty, for example, and the various *rollbase attributes contain macro text used to generate the standard template rolls for the abilities).

[edit] Attribute Replacements

NOTE: Attribute Replacements assumes you are utilizing the D&D 5E by Roll20 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.

[edit] Variant : Replace Attribute List

This new tag (--replaceattrlist) allows you to create replacement values for any number of attributes on your character sheet. This should work for any sheet (not limited to the D&D 5E by Roll20-sheet, or even to D&D).

Specify a prefix, followed by a semicolon delimited list of attributes to create values for:

 --replacementattrlist|S-|@{selected|character_id}|strength_mod;dexterity_mod;wisdom_mod 

Would create three replacement values : ~S-strength_mod$, ~S-dexterity_mod$, and ~S-wisdom_mod$ which would contain the corresponding values from the selected character.

[edit] Spell Replacements

Note: Spell replacements assumes you are using the D&D 5E by Roll20 character sheet

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.

[edit] NPC Action Replacements

Note: NPC Action replacements assumes you are using the D&D 5E by Roll20 character sheet

Another specialized replacement function, NPC action replacements require a character ID and an action name, and will create a number of replacement keys based on the information for the NPC action retrieved from the given character sheet.

 --replacenpcaction|@{selected|character_id}|Bite

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

For all NPC Actions:

  NPCA-NAME - The name of the action
  NPCA-TYPE - Either "ATTACK" or "INFOCARD", depending upon if the "Attack?" checkbox is selected for the action
  NPCA-DESCRIPTION - The text description of the action

In additon, if the action is marked as an attack:

  NPCA-ATYPE - The action type, either "Ranged" or "Melee"
  NPCA-RANGE - The range or reach of the attack
  NPCA-TOHIT - The "To Hit" bonus for the attack
  NPCA-TARGET - The (text-based) target information entered in to the action
  NPCA-DAMAGE - Primary damage roll for the attack
  NPCA-CRIT - Calculated primary critical hit damage (by doubling the number before the "d")
  NPCA-DAMAGETYPE - Primary damage type
  NPCA-DAMAGE2 - Secondary damage roll
  NPCA-CRIT2 - Calculated secondary critical hit damage (by doubling the number before the "d")
  NPCA-DAMAGETYPE2 - Secondary damage type

[edit] 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 D&D 5E by Roll20 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

[edit] Advanced API Usage

PowerCards supports calling the AlterBar API script(not in the One-Click API install), 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).

PowerCards doesn't automatically transfer token selection to any API it calls, so you need to use SelectManager^(Forum) as a go-between if you want to use @{selected|attribute} or similar.

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 Script: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

[edit] Other

[edit] Changelog

Version 3.8.11 (2019-02-19) GitHub PR

• introduce a new ancillary addon API called PowerCards Macro Helper, which automates PowerCard creation for D&D 5E by Roll20(aka. 5E OGL) games.

Version 3.8.8 (2018-11-13) GitHub PR

• Promoting lastest development version to OneClick Install

Version 3.8.5(2018-08-14) GitHub PR

• Modified the expanded conditionals feature to prevent potential undesirable use.

Version 3.8.4

• Added the --replacesection tag. See the details section of the wiki for further information. The intent of this tag is to provide replacements support for those not using the D&D 5E by Roll20 sheet.
• Added new conditionals that support some math functions. Please see the expanded conditionals section of the wiki for details.

Version 3.8.3

• It is now possible to assign attributes to characters that will override the default action buttons created by the --spell_list tag. This is similar to the way action macros can be assigned. Create an attribute on a character called "spell_SpellName_macro", replacing spaces in the spell name with underscores (so, spell_Guiding_Bolt_macro for example - the name is case sensitive, matching the name of the spell on the character sheet). and specify a macro as the attribute value (like #GuidingBolt), including the # sign. When the --spell_list tag processes each spell, it will check for a matching attribute and substitute the specified macro for the effect of the API button if that attribute exists. Also note that since the CharacterMancer update, spells need to be marked as prepared to show up on the spell list (the red circle needs to be filled in).

Version 3.8.2

• Added the --replacenpcaction tag. See the details section of the wiki for further information

Version 3.8.1

• 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 (2018-07-16

• 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(2018-06-09)

• 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.

Version 3.7.2 (2018-04-19) by Kurt J.

• Added to the API One-Click install dropdown

Version 2.4.11 (2015-03-28) by Sky - forum thread

• Update: Replaced target_info parsing logic with TheAaron's replacement. No change to macros needed.
• Update: Thanks to TheAaron, you can now format powercard macros on separate lines instead of as one long line

Version 1 (2014-07-31) by Sky

• The first release of the API script Forum Thread

[edit] History

PowerCards were first introduced to D&D in 4th Edition, and were consistently formatted blocks in the 4th Edition products that represented abilities. The format of the 4E cards is visually pleasing, and the original author of the PowerCards API script (Sky or SkyCaptain) took on the task of adding them to Roll20 to enhance VTT games. Since then, of course, D&D has moved on, but the visual representation allowed by the PowerCards API is still useful and appealing, even for non-D&D games.

Sky published Version 2.4.11 in March 2015.

Beginning with version 3.7.0(early 2018) of the API script, Kurt J. have taken over maintaining, updating, and expanding PowerCards. Over time, additional features have been added, and an ongoing quest is underway to lock down any outstanding issues that may cause sandbox crashes or other undesirable behavior.

Version 3.7.2 (Apr 19, 2018) 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.

[edit] 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 – Original Author of the PowerCards script
• Alex L.
• Brian
• Chris N.
• Rob J.
• The Aaron
• GenKitty
• Sean G
• Janick H.
• Kurt J. - Script Maintainer since 2018
• Andreas J. - wiki cleanup

[edit] See Also

• Complete Macro Guide
  • Order of Operations
  • Inline Rolls
• Script:PowerCards Macro Helper companion API for PowerCards
  • PowerCards - PCMHelper - 15min video on the PowerCards Helper, by Kurt Jaegers (February, 2019)
• PowerCards : Templates and Replacements (Jun 24, 2018)
  • a 35min introduction to the --template and --replacement-tags by Kurt Jaegers
• Roll20 PowerCards - Attribute-based Video and Audio Tags (April, 2018)
  • a 15min video by Kurt Jaegers showing the tags for v3.7.1
• Script:ScriptCards - Sript by thes same author that is fairly similar, but have different syntax and is more flexible
  • What to Know if you are Coming from PowerCards
• D&D 5E by Roll20 - Character sheet used in many examples