Difference between revisions of "Script:PowerCards"
From Roll20 Wiki
(→Inline Rolls) |
Andreas J. (Talk | contribs) m (→Anatomy of a PowerCard Macro) |
||
(18 intermediate revisions by 2 users not shown) | |||
Line 1: | Line 1: | ||
+ | {{revdate}} | ||
+ | |||
+ | PowerCards is an [[API|API script]] meant to show character stats, attributes & more in a consistently formatted blocks in the {{Text Chat}}, independently from [[Character Sheet]]'s [[Roll Templates]]. | ||
+ | |||
+ | {{notebox|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: [https://app.roll20.net/forum/post/7136858/script-powercards-3-thread-6 Script: PowerCards 3 (Thread 6)] | ||
{{script overview | {{script overview | ||
|name=PowerCards | |name=PowerCards | ||
Line 4: | Line 11: | ||
|version=3.8.11 | |version=3.8.11 | ||
|lastmodified=2019-02-19}} | |lastmodified=2019-02-19}} | ||
+ | '''[[Script:PowerCards Macro Helper|PowerCards Macro Helper]]''' is a useful companion API for PowerCards. | ||
[[File:Powercards-example.png|thumb|right|700px|Example of PowerCards from the [https://www.youtube.com/watch?v=JwUkdO-F3LQ PowerCards: Templates and Replacements]-introduction video ]] | [[File:Powercards-example.png|thumb|right|700px|Example of PowerCards from the [https://www.youtube.com/watch?v=JwUkdO-F3LQ PowerCards: Templates and Replacements]-introduction video ]] | ||
− | |||
− | |||
− | |||
__TOC__ | __TOC__ | ||
== Introduction == | == Introduction == | ||
+ | {{apiboxRec}} | ||
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. | 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. | ||
Line 34: | Line 40: | ||
== Anatomy of a PowerCard Macro == | == Anatomy of a PowerCard Macro == | ||
− | A PowerCard is created as the result of a chat string beginning with the | + | A PowerCard is created as the result of a chat string beginning with the {{c|!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 (<code><nowiki>{{</nowiki></code> and <code><nowiki>}}</nowiki></code>). These lines and options are identified by tags, which always start with two dashes ({{c|--}}) followed by the tag name. This is followed by a vertical bar (<code><nowiki>|</nowiki></code>) 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 | + | :''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 {{c|txcolor}}, {{c|bgcolor}} (both for the title portion of the card), <code>erowtx</code>, <code>erowbg</code>, <code>orowtx</code> and <code>orowbg</code> tag. <code>e</code> is for even rows, <code>o</code> is for odd rows, <code>tx</code> refers to "text color", and <code>bg</code> 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. | 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. | ||
Line 79: | Line 85: | ||
* '''ANY''' roll that is hidden from the chat server (by being in a template, or surrounded with [#[ and ]#] instead of <nowiki>[[ and ]]</nowiki>, or any other means) '''''must''''' use a Roll ID, or you will get a syntax error when the system tries to process the roll. | * '''ANY''' roll that is hidden from the chat server (by being in a template, or surrounded with [#[ and ]#] instead of <nowiki>[[ and ]]</nowiki>, or any other means) '''''must''''' use a Roll ID, or you will get a syntax error when the system tries to process the roll. | ||
− | |||
==Tags == | ==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 | + | 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 <code>--</code> and a vertical bar character <code><nowiki>|</nowiki></code> separates the tag from its content. Everything after the vertical bar up until the next tag is encountered (specified by <code>--</code> again) is considered the content of the tag. |
Tag Format Examples: | Tag Format Examples: | ||
Line 92: | Line 97: | ||
BAD: -BadTag<nowiki>|</nowiki> This is also a bad tag. | BAD: -BadTag<nowiki>|</nowiki> This is also a bad tag. | ||
− | '''Important Note about Replacement Notation (@{})''': | + | '''Important Note about Replacement Notation (<code>@{}</code>)''': |
− | 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: | + | The <code>@{}</code> notation (<code>@{target|hp}</code> 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]] | --hroll|[[ [$HPchecker] @{target|Target1|bar3} % @{target|Target1|bar3|max} * 100 + 0d0]] | ||
Line 102: | Line 107: | ||
--hroll|[[ [$HPchecker] 15 % 30 * 100 + 0d0]] | --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: | + | 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 <code>@{}</code> 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]] | --hroll|[[ [$HPchecker] % * 100 + 0d0]] | ||
Line 132: | Line 137: | ||
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. | 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, | + | ''Note: As of version 3.8.3, using a RollID in a repeat tag will append <code>_#</code> to the RollID, where <code>#</code> is the iteration of the repetition. For example, <code><nowiki>--Attack#3|Fred rolls [[ [$atk] 1d20 ]]</nowiki></code> will result in three RollIDs called <code>atk_1</code>, <code>atk_2</code>, and <code>atk_3</code> containing the results of each roll. |
|- | |- | ||
− | | style="white-space:nowrap" | 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). | + | | style="white-space:nowrap" | 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 <code>--Attack*1</code> and <code>--Attack*2</code>, along with <code>--Miss*1 </code>and <code>--Miss*2</code>). |
Example: --Tag *1|Content | Example: --Tag *1|Content | ||
Example: --Tag *2|Content | Example: --Tag *2|Content | ||
Line 201: | Line 206: | ||
Example: --emote<nowiki>|</nowiki>!This emote would not have an avatar. | Example: --emote<nowiki>|</nowiki>!This emote would not have an avatar. | ||
|- | |- | ||
− | | style="white-space:nowrap" | --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. | + | | style="white-space:nowrap" | --emotefont || This tag will inject CSS into the emote section of the PowerCard's output. This property defaults to <code>"font-family: Georgia, serif; font-weight: bold; "</code> 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 <code>--charid</code> or the <code>--tokenid</code> tag for the <code>--emotefont</code> tag to take effect. |
Example: --emotefont<nowiki>|</nowiki>font-family: "Script"; font-weight: bold; | Example: --emotefont<nowiki>|</nowiki>font-family: "Script"; font-weight: bold; | ||
|- | |- | ||
Line 223: | Line 228: | ||
=== Character Sheet Information Tags === | === 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. | + | 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: <code>--npc_action_list|@{selected<nowiki>|</nowiki>character_id}</code> | Example: <code>--npc_action_list|@{selected<nowiki>|</nowiki>character_id}</code> | ||
Line 339: | Line 344: | ||
== Inline Rolls == | == Inline Rolls == | ||
− | The content portion of a tag can include any number of inline dice rolls. Inline | + | 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<nowiki>|</nowiki>Score of <nowiki>[[</nowiki> 1d20 <nowiki>]]</nowiki> vs AC. | Example: --Attack<nowiki>|</nowiki>Score of <nowiki>[[</nowiki> 1d20 <nowiki>]]</nowiki> vs AC. | ||
Example: --Attack<nowiki>|</nowiki>Score of <nowiki>[[</nowiki> 1d20 + 5 <nowiki>]]</nowiki> vs AC. | Example: --Attack<nowiki>|</nowiki>Score of <nowiki>[[</nowiki> 1d20 + 5 <nowiki>]]</nowiki> vs AC. | ||
Line 346: | Line 351: | ||
Example: --Attack<nowiki>|</nowiki>Score of <nowiki>[[</nowiki> 1d20 [Base] + 3 [Strength] + 2 [Proficiency] <nowiki>]]</nowiki> vs AC. | Example: --Attack<nowiki>|</nowiki>Score of <nowiki>[[</nowiki> 1d20 [Base] + 3 [Strength] + 2 [Proficiency] <nowiki>]]</nowiki> vs AC. | ||
− | It is also possible to specify attributes from character sheets using the <nowiki>@{}</nowiki> notation. The tag below combines this with the naming of modifiers: | + | It is also possible to specify attributes from character sheets using the <code><nowiki>@{}</nowiki></code> notation. The tag below combines this with the naming of modifiers: |
Example: --Attack<nowiki>|</nowiki><nowiki>[[</nowiki> 1d20 + @{selected<nowiki>|</nowiki>dexterity_mod} [Dexterity] <nowiki>]]</nowiki> | Example: --Attack<nowiki>|</nowiki><nowiki>[[</nowiki> 1d20 + @{selected<nowiki>|</nowiki>dexterity_mod} [Dexterity] <nowiki>]]</nowiki> | ||
Line 515: | Line 520: | ||
== Conditionals == | == 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). | + | '''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 [[OoO|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 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. | ||
Line 536: | Line 541: | ||
?? LeftValue OPERAND RightValue ?? | ?? LeftValue OPERAND RightValue ?? | ||
− | LeftValue and RightValue can be a number, a roll id ($Roll), or a roll query ( ?{target<nowiki>|</nowiki>AC} ), or even an attribute reference ( @{selected<nowiki>|</nowiki>attribute} ). | + | LeftValue and RightValue can be a number, a roll id ($Roll), or a roll query ( <code>?{target<nowiki>|</nowiki>AC}</code> ), or even an attribute reference ( <code>@{selected<nowiki>|</nowiki>attribute}</code> ). |
OPERAND can be one of the following: | OPERAND can be one of the following: | ||
Line 621: | Line 626: | ||
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. | 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. | ||
+ | === 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: | ||
+ | |||
+ | <pre> | ||
+ | !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! | ||
+ | }} | ||
+ | </pre> | ||
+ | |||
+ | 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...": | ||
+ | |||
+ | <pre>!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 | ||
+ | }} | ||
+ | </pre> | ||
+ | |||
+ | 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.''' | ||
+ | |||
+ | == 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: | ||
+ | |||
+ | <pre> | ||
+ | --skipTo|EndOfCard | ||
+ | </pre> | ||
+ | |||
+ | 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: | ||
+ | |||
+ | <pre>--:EndOfCard|</pre> | ||
+ | Note that skipto and label names are not case sensitive. | ||
+ | |||
+ | Example: | ||
+ | |||
+ | <pre> | ||
+ | !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| | ||
+ | }} | ||
+ | </pre> | ||
+ | |||
+ | 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. | ||
== Templates == | == Templates == | ||
Line 960: | Line 1,052: | ||
== Advanced API Usage == | == 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 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 {{fpl|9817678/ SelectManager}} as a go-between if you want to use <code>@{selected|attribute}</code> or similar.''' | ||
::{| class="wikitable" | ::{| class="wikitable" | ||
Line 970: | Line 1,064: | ||
Example: --api_token-mod<nowiki>|</nowiki>_ids @{selected<nowiki>|</nowiki>token_id} _ignore-selected _set statusmarkers<nowiki>|</nowiki>blue | Example: --api_token-mod<nowiki>|</nowiki>_ids @{selected<nowiki>|</nowiki>token_id} _ignore-selected _set statusmarkers<nowiki>|</nowiki>blue | ||
− | This example calls the [[TokenMod]] API script to set the “blue dot” status marker for the selected token. | + | This example calls the [[Script:TokenMod]] API script to set the “blue dot” status marker for the selected token. |
|} | |} | ||
+ | |||
'''''API-Specific Notes:''''' | '''''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 <code>!token-mod --configure players-can-ids|on</code> | '''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 <code>!token-mod --configure players-can-ids|on</code> | ||
− | |||
==Other== | ==Other== | ||
Line 1,067: | Line 1,161: | ||
=See Also= | =See Also= | ||
− | * [[ | + | * [[Complete Macro Guide]] |
− | * [[Script:PowerCards Macro Helper]] companion API for PowerCards | + | ** [[Order of Operations]] |
− | ** | + | ** [[Inline Rolls]] |
− | * | + | * '''[[Script:PowerCards Macro Helper]]''' companion API for PowerCards |
− | + | ** {{yt|watch?v=PVjs39dzaUA|Roll20 PowerCards - PCMHelper}} - 15min video on the PowerCards Helper, by {{user profile|2365448|Kurt Jaegers}} (February, 2019) | |
− | * | + | * {{yt|watch?v=JwUkdO-F3LQ | PowerCards : Templates and Replacements}} (Jun 24, 2018) |
+ | ** a 35min introduction to the <code>--template</code> and <code>--replacement</code>-tags by {{user profile|2365448|Kurt Jaegers}} | ||
+ | * {{yt|watch?v=JwUkdO-F3LQ | Roll20 PowerCards - Attribute-based Video and Audio Tags}} (April, 2018) | ||
+ | ** a 15min video by {{user profile|2365448|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 | ||
+ | ** [[Script:ScriptCards#What_to_Know_if_you_are_Coming_from_PowerCards| What to Know if you are Coming from PowerCards]] | ||
+ | * '''[[D&D 5E by Roll20]]''' - Character sheet used in many examples | ||
+ | |||
+ | [[Category:API Commands]] |
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)
Version: 3.8.11
Last Modified: 2019-02-19
Code: PowerCards
Dependencies: None
Conflicts: None
PowerCards Macro Helper is a useful companion API for PowerCards.
![](/images/3/37/Powercards-example.png)
[edit] Introduction
Roll20 Mod
Mod Suggestions
- D&D 5E
- Combat
- Character Sheet
- Dynamic Lighting
- Jukebox
- Maps
- Text Chat/Macros
- Tokens
- System Specific
- Mod Guides by Script
Debug
Other
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
andorowbg
tag.e
is for even rows,o
is for odd rows,tx
refers to "text color", andbg
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 calledatk_1
,atk_2
, andatk_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 ofEffect_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
Parameter | Description |
---|---|
character_id | character_id} |
entryname | The replacement section entry you are looking for. For example, in the D&D 5E by Roll20 sheet, if you were looking for a PC attack in the repeating_attack section called "Warhammer", entryname would be "Warhammer". ' |
sectionname | The name of the repeating section you will be checking for entryname. "repeating_" will be prefixed to this name, so if "npcaction" is passed as the sectionname, the "repeating_npcaction" section will be searched. |
searchtext | This is the particular attribute in the repeating section that entryname will be compared against. For example, in the D&D 5E by Roll20 sheet, the repeating_npcaction section contains an attribute called "name". The expanded form of this might be "repeating_npcattack_$0_name". In this case, the value of searchtext is "name". |
replacementprefix | This parameter defines the prefix that will be placed in front of every returned replacement value key. This allows you to use multiple replacesection commands in the same macro, as they can all be given a unique prefix. |
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:
- Active/Selected Character Token ID
- Target Character Token ID
- Action being performed by Selected Character
- Name/Header of the PowerCard
- Text for the left side subtitle
- 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
- 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
- a 35min introduction to the
- 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
- D&D 5E by Roll20 - Character sheet used in many examples