Reporter has been updated to One Click
Reporter
A script to poll the VTT and return info on Token/Character pairs, along with customized action tools
This is a script I have been working on for a couple of months. I don't think it's quite polished enough to send to one-click yet—it's too easy to get garbage results if the syntax isn't just right.
Reporter is a script that reads the tokens on the board that are associated with character sheets and builds a report of them in the chat, returning selected values from either the token settings or the character sheets they are associated with. You can either select a set of tokens to work with, or if you select no tokens, it will assume all tokens on the Object/Token layer. To run the script on other layers, you must specifically select tokens, though. The basic syntax is:
!report[filters] --[queries] ---[buttonline] ----[keywords]
Filters
Filters have changed since v.0.x. Please check any previous macros. This was changed to make parsing possible for running multiple filters on the same report.
By default, reporter uses the selected tokens to run a query, or if no tokens are selected, all tokens on the token/objects layer.
You may wish to constrain a report to only tokens which match a specific set of criteria. For example, you might have 50 tokens on the table, but 10 of them are goblins, and you only want to work with the goblins. Or you want to find all the characters who are both PCs and have darkvision. You can add filters after the !report command. The filter is written using a similar syntax to a query, followed by the filter term. In essence, it is querying each token for a match. The syntax is:
!report||operator|source|attribute|value
You can add more filters just by adding double pipes to the end of the first filter and typing another.
There are four types of operator.
+ only includes the token/character pairs that matches the query
- excludes any token/character pair that exactly matches the query
~ only includes any character that is a partial match for the query
^ excludes any character that is a partial match for the query
thus:
!report||-|c|name|Goblin will return all tokens that are not represented by the Goblin character sheet.
!report||~|c|name|Goblin will return any tokens that are represented by the Goblin or Hobgoblin character sheet.
!report||-|c|npc|1||+|t| has_night_vision|true will exclude all NPCs (leaving only PCs), and then only return those that have nightvision set.
Filters do not support an alias, because they are never displayed in the final report.
Filters are executed sequentially, with each filter working on the result from the last, so some logic is required for best results.
Filters are case insensitive.
There is as yet, no way to test for an empty, or undefined value.
Queries
Queries are constructed usingt|attribute to poll a token attribute
c|attribute to poll a character sheet attribute
Examples
!report --t|name would return a report of all selected token names
!report --c|strength would return a report of all strength values on the character sheets of the selected tokens
For character sheets, the script will try to pull a value from the character journal first, and if that does not exist, the installed character sheet. At this point in time, Reporter cannot return information that requires a callback, such as the GMNotes field.
Dividers
You may not always want each attribute reported on its own line. You can add a code after the attribute name(not the alias) to use something either than a line return between attributes
comma (,) Adds three non-breaking spaces between this attribute and the next, keeping them on the same line when possible.
period (.) Adds a vertical pipe between this attribute and the next, keeping them on the same line when possible.
dash (-) Adds a thin gray horizontal rule between this attribute and the next.
Hashtag (#) Adds a bit of horizontal space between this attribute and the next.
Examples:
!report --t|emits_bright_light,|Bright-Light t|bright_light_distance|Distance t|emits_low_light,|Low-Light t|low_light_distance|Distance ---light
will return this:
Aliases
There are times in the report when you would not like 'has_bright_light_vision' in the report. You can substitute an alias for the attribute name that will display in chat. For this, just add another pipe after the query and type an alias.
For example, if a token has 60 feet of Night Vision:
t|night_vision_distancemight produce:
T: night_vision_distance = 60
but
t|night_vision_distance|NVwould yield:
T: NV= 60
If you use a hyphen (-) as the alias, it will display no label at all. You can turn on or off the graphic for the source (token or character) with source keyword described below.
Buttonline
The buttonline is a string containing text and Ability or API Command buttons. These are formed using the normal syntax for buttons: [button name](command) with a few exceptions. In order to keep the Roll20 parser from resolving queries and attribute calls before the script gets them, they need to be written slightly differently.Examples:
@{token|name} is written as A{token|name}
?{question|default_answer} is written as Q{question|default_answer}
Further, for a handful of scripts, the Reporter API will attempt to parse the code so that each buttonline refers to the specific token being reported on. Currently Token Mod, ChatSetAttr and Supernotes are supported. It does this by injection the token id into the script calls for those scripts. Because of this, do not use --ids in a token-mod call, ChatSetAttr call, or --id in a Supernotes call.
Special Codes
Reporter contains a few special codes for common cases, to make macro writing easier. You can put these in place of normal commands:--vision as the Query will replace any declared query line with one designed to report most vision situations. It will give values for whether the token has sight, night vision and what the distance of any night vision is.
---vision as the Buttonline will replace any declared button line with a buttonline designed to handle most cases of vision and darkvision.
--light as the Query will replace any declared query line with one designed to report most lighting situations. It will give values for the amount of light, distance and what type.
---light as the Buttonline will replace any declared button line with a buttonline designed to handle most cases of lighting.
The buttonline codes require the installation of the Token-mod API.
Keywords
Keywords change the overall appearance or scope of the report. They are separated from the rest of the report by four dashes and must come at the end.
layer|[gmlayer|objects|map|walls|tracker|all] will constrain the report to a particular layer or all layers at once, so long as no tokens are selected. If any tokens are selected, Reporter will default to the layer the selected tokens are on. This makes it easier for instance to check the vision settings of tokens on the token layer and the gmlayer simultaneously, or to ping pull to note tokens on the gm layer without switching manually to that layer.
If the layer keyword all is used the report will be on all token/character pairs on all layers. In this case, a layer character will appear on each subhead line of the report to let you know which layer the token is on.
If the layer keyword tracker is used the report will be on all token/character pairs on the Turn Tracker as if it were a layer. In this case, a layer character will appear on each subhead line of the report to let you know which layer the token is on. If you click on the layer token, it will switch the token from the GM/Notes layer to the Token/Objects layer and back.
compact|[true|false] (default=false): The compact mode shows the token image at half size, and eliminates the second line of the report subhead, since it is not always desired. You may have a very large report you want to see better, or you may be using a sheet that does not support the default values. Currently the second line of the subhead only references the D&D 5th Edition by Roll20 Sheet.
showheader|[true|false] (default=true): This will control whether the header will display at the top of the report.
showfooter|[true|false] (default=true): This will control whether the footer will display at the bottom of the report.
printbutton|[true|false] (default=true): This will control whether the print button will display on each line of the report.
notesbutton|[true|false] (default=false): This will control whether a notes button will display on each line of the report. This notes button will return the token notes for the token on that line. The visibility of the notes button is controlled by the visibility keyword. If the visibility is "gm", it will use a !gmnote command, if the If the visibility is "whisper", it will use a !selftnote command, and if the visibility is "all", it will use a !pcnote command.
visibility|[gm|whisper|all] (default=gm): This will determine how the report is presented. "gm" is whispered to the gm, "whisper" is whispered to the user who sent the command, "all" is posted openly for all to see.
showfooter|[true|false] (default=true): This will control whether the footer will display at the bottom of the report.
source|[true|false] (default=true): if source is set to false, the C and T characters that show whether an attribute comes fromthe token or the sheet will not be displayed. Use this is they are a distraction.
charactersheetlink|[true|false] (default=true): if this keyword is set to false, the link to open the token's corresponding character sheet will not display
subtitle|[true|false] (default=true): if this keyword is set to false, the line directly below the character name will not display. (This is also the default in Compact mode). This may be desirable if not using the D&D 5th Edition by Roll20 Sheet.
ignoreselected|[true|false] (default=false): if this keyword is set to true, the search will not be preset to whichever tokens are selected. The report will run as if no tokens were selected, following whatever layer criteria might have been specified.
npcsubstitutions[true|false] (default=true): if this keyword is set to false, the script will not automatically substitute npc attributes for their PC counterparts (ex: npc_senses for passive_wisdom).This is good for sheets that are not the D&D 5th Edition by Roll20 Sheet.
sort|attribute (default is the raw order): This keyword will sort the final list. Most of the sorts are confined to the token attributes, since they require internal code and if they refer to a sheet may return poor or no results if the sheet does not have the proper attributes. Currently the following values can be sorted on:
charName: character name. Sheet must have a "name" attribute.
charNameI: character name, inverse order. Sheet must have a "name" attribute.
tokenName: token name
tokenNameI: token name, inverse order.
bar1: token bar1 value
bar1I: token bar1 value, inverse order.
bar2: token bar2 value
bar2I: token bar2 value, inverse order.
bar3: token bar3 value
bar3I: token bar3 value, inverse order.
cr - Challenge Rating. D&D 5th Edition by Roll20 Sheet only
crI - Challenge Rating, inverse order. D&D 5th Edition by Roll20 Sheet only
title|Title| If this is present in the keywords, the string in between pipes will be placed at the top of the report. If you only want the custom title to display, be sure turn off the header with showheader|false. The title must be placed between two pipes. title|My Title| will work. title|My Title will break.
Examples:
!report ---- layer|gmlayer compact|true
will report on all the tokens on the gm layer in compact mode.
!report ---- layer|tracker compact|true title|Tracker Navigator| showheader|false showfooter|false
will produce a compact report that will allow you to navigate around the tracker tokens on the board, with links to ping pull, switch layers, open character sheets and more.
A more full featured Turn Tracker could include more info and macros:
!report --c|strength,|Str c|strength,|Dex c|strength|Con c|strength,|Int c|strength,|Wis c|strength#|Cha t|bar1_value,|HP c|npc_ac|AC c|npc_senses|perception t|statusmarkers|Condition ---[Apply Damage](!token-mod --set bar1_value|Q{Enter damage amount. Use positive or negative to modify values|-0}) | [Apply Condition](!token-mod --set statusmarkers|Q{Choose Status|Dead,dead|Bloodied,red}) ----layer|tracker compact|true title|Tracker Display| showheader|false showfooter|false source|false
How to Read a Report
Header. The header of the report will list the range of tokens being reported, by name, followed by the count. The second line is 5e-specific right now, but I'll probably put in some options in the next version.
Report Line. The report line of each item will show an image of the token, followed by its token name and the associated character sheet name. If the character sheet is a renamed NPC statblock. ex. If Captain Hero is using the Veteran sheet, it will note this. It will also not if any of the characters have the PC flag.
The second line of the report will display the creature type for NPCs or the class and level for PCs. This is specific to the D&D 5th Edition by Roll20 Sheet and will probably return undefined on other sheets. This is a feature in development.
Click on:
Token image - Ping pull all players to the token's location.
Token Name - Ping pull only GM to the token's location. Invisible to players.
Character Name - Opens the associated character sheet.
Then follows a list of the attributes being requested.
Tindicates a token attribute.
Cindicates a character attribute.
The display of the source character can be turned off with the keyword source|false.
Button Line. This is the list of commands that can be performed on each token. If it is a token-mod command, or a Supernotes command, it will be specific to that token. Refer to Button Line documentation above for details.
Special Buttons. There are a few buttons that appear in the report, at various places on the right side.
☰ will call up the report script menu
⟲ will repeat the command that created the report, in case you want to confirm that changes were made.
w will echo to the chat whatever is on that line: Token name on a report line, or Page name on the page line of the header.
One-line codes
The following are special codes that expand behind the scenes into full-featured macros, and handle some of the more common uses for Reporter. They are available through the menu button, or you can copy the code as displayed into any macro.
- !report --vision ---vision - Use this command to check the vision of selected tokens. If you have no selected tokens, it will return a report of all tokens on the Token/Objects layer.
- !report|vision - Shorthand for the above command. --vision and ---vision are special keywords that can be used as substitutes in any reporter macro.
- !report --light ---light - Use this command to check the lighting of selected tokens. If you have no selected tokens, it will return a report of all tokens on the Token/Objects layer.
- !report --light ---lightplus - A more detailed version of the above, with most common light sources.
- !report|light - Shorthand for the above command. --light, ---light and ---lightplus are special keywords that can be used as substitutes in any reporter macro.
- !report|help - Use this command display the documentation for the Reporter script. Also accepts !report --help
- !report|mapkeys - Use this command to display a list of all objects on the gm layer that represent a character called Map Key You can use this to navigate around a map quickly and call up any token notes that might be placed in the Map Key tokens.
- !report|mapkeys_sorted - As above, but sorted alphabetically.
- !report|pcs-detail - A detailed display of all PCs on the map.
- !report|pcs - A compact display of all PCs on the map.
- !report|npcs-detail - A compact display of all PCs on the map.
- !report|npcs-actions - A detailed display of all PCs on the map with most token action buttons displayed. Works very well with the Token Action Maker script.
- !report|tracker - A compact display of all characters in the Turn Tracker.
- !report|tracker-actions - A display of all characters in the Turn Tracker with most token action buttons displayed.
- !report|report - How to read the report. Also accepts !report --report
"That's all great Keith, but what can I use this for?"
I originally wrote this to be a tool to check lighting and vision for each token on each page in a module. And there are some built-in shortcuts that allow for quickly doing this. !report --vision and !report --lighting for queries will return the important values for tokens regarding what they can see and what light they cast. Similarly, there are built in button lines for setting vision and lighting. !report --vision ---vision and !report --lighting ---lighting will give you reports for each token, and the appropriate buttons to control those values. The graphic above shows the default vision macro. This is what the default lighting report line looks like:
Where's the code?
This has been updated to One Click installation. Please see the new thread.
