Character Vault
Any Concept / Any System
Compendium
Your System Come To Life
Roll20 for Android
Streamlined for your Tablet
Roll20 for iPad
Streamlined for your Tablet

Personal tools

Difference between revisions of "Script:PowerCards"

From Roll20 Wiki

Jump to: navigation, search
(Text Formatting)
(Installation and Configuration)
Line 14: Line 14:
 
== Installation and Configuration ==
 
== Installation and Configuration ==
 
PowerCards is available via the one-click install mechanism in the API page for your Roll20 game. Alternatively, you can copy the script's code, available from the menu on the right and stored at Roll20's [https://github.com/Roll20/roll20-api-scripts API GitHub Repository]. Paste the code into a new script in your campaign's [[API:Use_Guide#The_Script_Editor|API Script Editor]]. Save the new script and it will be available inside your campaign.
 
PowerCards is available via the one-click install mechanism in the API page for your Roll20 game. Alternatively, you can copy the script's code, available from the menu on the right and stored at Roll20's [https://github.com/Roll20/roll20-api-scripts API GitHub Repository]. Paste the code into a new script in your campaign's [[API:Use_Guide#The_Script_Editor|API Script Editor]]. Save the new script and it will be available inside your campaign.
 +
 +
Updates to the PowerCards API are released first on the development GIST linked above, and every few versions will be synced to the One-Click Install system. For the latest and greatest features (and possibly interesting bugs too!) check out the development GIST.
  
 
== Important Clarifications ==
 
== Important Clarifications ==

Revision as of 22:52, 13 June 2018

API ScriptAuthor: Sky, Kurt J.
Version: 3.7.1
Last Modified: 2018-04-12
Code: PowerCards
Dependencies: None
Conflicts: None

PowerCards allows you to define highly customizable templated output for PC and NPC actions, spells, abilities, statistics, or almost any other purpose you can come up with. Their original purpose was to present ability and attack information (powers) in a format similar to the power blocks from the official D&D 4E products, but the format works well for any system. PowerCards are output to the chat window with full HTML/CSS formatting. A handful of options use information from the 5E OGL sheet, but these options are not critical to the functioning of the core features of the script.

Contents

Syntax

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

Installation and Configuration

PowerCards is available via the one-click install mechanism in the API page for your Roll20 game. Alternatively, you can copy the script's code, available from the menu on the right and stored at Roll20's API GitHub Repository. Paste the code into a new script in your campaign's API Script Editor. Save the new script and it will be available inside your campaign.

Updates to the PowerCards API are released first on the development GIST linked above, and every few versions will be synced to the One-Click Install system. For the latest and greatest features (and possibly interesting bugs too!) check out the development GIST.

Important Clarifications

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

  • 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 TAGS MUST BE UNIQUE. This is true even when dealing with conditional lines. See the same name tag modifier below.
  • The results of a conditional line only determine if the line output is shown on the PowerCard, and does not prevent the line from running. 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.
  • Selected/Target notation (ie, @{selected|token_id}) replacement happens on the chat server before PowerCards gets the command. This means PowerCard will get the VALUE of these replacements, and not any kind of reference to what the original replacement text was.

Script Use

For screenshots and other information, please see this thread https://app.roll20.net/forum/post/6264588/script-powercards-3-thread-5

A PowerCard is 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.

Any line that doesn’t contain a reserved tag (see below) name will be displayed as bold text followed by the tag contents. In this case, a 1d20 is being rolled (die rolls are specified by enclosing them in double square brackets) , followed by the rest of the text in the content of the tag.

 !power {{ 
 --name|Melee Attack
 --Attack:|[[ 1d20 ]] vs AC 
 --Damage:|Target takes [[ 1d8 + 2 ]] damage on a hit.
 }}

Recent Change Log

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

Version 3.7.6

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

Version 3.7.5

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

Version 3.7.4

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

Version 3.7.3

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

Using Tags

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

Tag Format Examples:

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

Important Note about Replacement Notation (@{}):

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

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

PowerCars actually gets something along the lines of:

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

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

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

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

Tag Modifiers

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

Modifier Description
Hide Tag Adding an exclamation mark (!) at the start of a tag will hide that tag’s name and not display it in the power card, but it will show the contents of the tag in the card. This is useful for adding blocks of text without a tag.
   Example: --!Tag|Content
Indent Adding a caret mark (^) followed by a number will indent that entire line and its contents slightly. The indentation option ranges from a minimum of zero (used to reset the indent to default) to a maximum of nine, though at nine, you will not have very much room for content at all.
   Example: --^1Tag|Content

The indent tag option can be used in conjunctions with the hidden tag option, but the exclamation mark must be first.

   Example || --!^1Tag|Content
Repeat To repeat a tag and its contents, add a hash mark (#) followed by the number of times you want the content to repeat. You can also use roll queries to add a pop-up in roll20 to determine the number of times to repeat the tag when you click the macro (see second example).
   Example: --Damage#3|[[ 1d8 ]] slashing damage
   Example: --Attack#?{Number of attacks|1}|[[ 1d20 + 4 ]]

Using the repeat tag will generate unique rolls for each inline roll in each repeated tag, and a card line for each iteration of the effect.

Same Name This tag option is used to enable the use tags with the same name. Unlike repeating tags, the content is unique to each tag of the same name. To use this tag, add an asterisk * followed by a number. The number used must be unique for that instance of a tag across the whole card (So you can have --Attack*1 and --Attack*2, along with --Miss*1 and --Miss*2).
   Example: --Tag *1|Content
   Example: --Tag *2|Content
Hide Tag & Content Add a $ in front of the tag to hide the tag and the content. This can be combined with a roll query to make this configurable on the fly.
    Example: --$Tag|Content
    Example: --?{Hit delete to show Hex damage|$}Hex:|[[1d6]] necrotic damage

Formatting and Configuration Tags

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

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

Other Reserved Tags

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

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

Character Sheet Information Tags

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

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

These tags are:

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

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

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


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

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

Audio and Video Effects

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

Tag Description
--soundfx This tag sends an api command to the Roll20 Audio Master (R20AM) script available as a one-click script install. Follow the link for more information on how to use R20AM.
   Example: --soundfx|_play|Bite
   Example: --?? $Atk >= @{target|AC} ?? soundfx *1|_play|Shortbow
--vfx_opt This tag accepts 1, 2, or 3 parameters separated by spaces. If a single parameter is passed, it is used as the effect descriptor (eg, burst-magic) and the effect is played at the card's Token_ID token location.
   Example: --vfx_opt|burst-slime

If two parameters are passed, the first parameter is the token who's location will be used for the effect, and the second is the descriptor. Use the format for single-location effects (burst, explosion, nova, etc).

   Example: --vfx_opt|@{target|token_id} glow-blood

Finally, if three parameters are passed, the first is the effect starting location, the second is the effect destination location, and the third is the effect descriptor. Use this format for effects that appear between two points (beam, breath, etc).

   Example: --vfx_opt|@{selected|token_id} @{target|token_id} breath-fire
--audioattr Similar to the --soundfx tag, this tag still requires the use of the Roll20 Audio Master script. This tag requires two parameters. The first is a token id, and the second is an attribute name. If the given attribute exists on the character that the token represents, it will be passed (without editing) to the !roll20AM command. For example:
   Example: --audioattr|@{selected|token_id} Audio_OnAttack

When the PowerCard is displayed, it will check the charactersheet represented by the selected token. If Audio_OnAttack exists as an attribute, it will retrieve the value of the attribute and pass it to Roll20 Audio Master. If, for example, the Audio_OnAttack attribute for a dragon was "--play|FireBreath", the corresponding "FireBreath" sound effect track will be played (assuming you HAVE a FireBreath sound effect in your jukebox).

--vfxattr A companion to the --audioattr tag, this new tag takes two parameters as well: a token id and an attribute name. It will check the character represented by the token for the specified attribute. If it is found, the script will interpret the contents of the tag and set up a visual effect:
   Example: --vfxattr|@{target|token_id} Effect_OnHit

When this tag fires, it will check the targeted token for an attribute called Effect_OnHit. If it exists, it will be parsed to create a visual effect. Because @{} token references are parsed by the chat system and not the API, we can't directly specify things like @{selected|token_id} in the attribute, so instead we interpret "s" as the selected token and "t" as the target. This means the value of Effect_OnHit could be something like:

   s t beam-magic

Which will cause a point-to-point magic beam effect starting at the selected token (s) and pointing at the target token (t). This attribute value:

   t glow-blood

Will cause a burst of blood on the target token.

PLEASE NOTE: Video effects are played on the active player page (where the Player ribbon is positioned). It is easy to forget this when testing effects on a page the players can't see.

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

Advanced API Usage

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

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

This example calls the TokenMod API script to set the “blue dot” status marker for the selected token.

API-Specific Notes:

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

Inline Rolls

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The full list of these options are:

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

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

Text Formatting

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

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

HTML Tables

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

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

The formatting characters are:

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

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

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

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

The Format Handout

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

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

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

  Example: --format|bigbad

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

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

Target Info Charms

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

  • You MUST specify a --target_list tag, even if there is only a single target.
  • If a tag uses a charm, that target is “consumed” for the purposes of further charm use in the PowerCard. In other words, the first tag to use a charm references the first target in the target list, and is the ONLY tag that will be able to reference that target (with charms). The second tag containing charms uses the next target, etc. If you need multiple lines, insert line break characters (^^) into the content.
  • Charm names are case sensitive, so AC, ac, Ac, and aC are all different names.
 Example: !power {{ 
 --name|Single Target Attack --target_list|@{target| |token_id} 
 --Attack|[[1d20+5]] | [[1d20+5]] vs %%AC%% Armor Class (%%token_name%%) --Hit|[[1d8+3]] slashing damage }}
 Example: !power {{ 
 --name|Scorching Burst | Nine Targets 
 --target_list|@{target|1st|token_id} | @{target|2nd|token_id} | @{target|3rd|token_id} | @{target|4th|token_id} | @{target|5th|token_id} | @{target|6th|token_id} | @{target|7th|token_id} | @{target|8th|token_id} | @{target|9th|token_id} 
 --Attack#?{Number of targets|1}|[[1d20+5]] vs %%Reflex%% Reflex (%%token_name%%) 
 --Hit|[[1d8+3]] fire damage 
 }}

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

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

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

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


Conditionals

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

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

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

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

Conditionals are structured in the format:

 ?? LeftValue OPERAND RightValue ??

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

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

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

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

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

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

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

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

 Sky – The original author of the mod… I’ve just taken over updating it :)
 Alex L.
 Brian
 Chris N.
 Rob J.
 The Aaron
 GenKitty
 Sean G
 Janick H.