Roll20 uses cookies to improve your experience on our site. Cookies enable you to enjoy certain features, social sharing functionality, and tailor message and display ads to your interests on our site and others. They also help us understand how our site is being used. By continuing to use our site, you consent to our use of cookies. Update your cookie preferences .
×
Create a free account

[Script] Inspector - A data inspection tool especially for the curious, or those looking to write scripts

1666731513

Edited 1666796247
timmaugh
Pro
API Scripter
Inspector FILE LOCATION:   My Personal Repo  (beta) - 1-click version will update after beta DEPENDENCIES : Inspector needs Messenger (currently also in beta release in my repo ) and libTokenMarkers (available in the one-click). If you install Inspector without either of these, you'll get a prompt to rectify that issue... but the instructions will point you to the one-click. For Messenger, you will need to install it from the link above (my repo) until Messenger makes it to the one-click. ABSTRACT: Inspector  is a tool for those curious about data in their Roll20 game, especially those who might be thinking about starting down the scripting road. Use simple command line switches to produce panels of information in formatted-JSON, complete with hover-tips, links, and browsable extended returns. Inspector  is designed to help you easily look at objects in your game and view their properties. Search by id, name, type, or other specialized parameters. All objects answering to that identifying piece of information will be reported, allowing you to examine them more closely. Roll20 object IDs are detected in the output and turned into links so that you can navigate from one object to a related object easily. Here are the particulars of the script's use. Command Line Use  !about  followed by arguments of the things you want to inspect. (Using just  !about  will produce a help panel of this same information in your game.) Arguments should be set off with double hyphens: !about --Kraang the Conciliatory Multiple arguments can be included. Each will produce a panel of returns. !about --Fire Ball --Kraang the Really Quite Agreeable You can enter the name of any game object -- a page, handout, character, player, etc. You can also show objects of a particular type, or show items of a particular type (children) that are related to a particular object (the parent). Returns If your argument returns a single thing (for instance, you have only one thing named 'Start'), you will see a detailed breakdown of the way that object is structured in your game, allowing you to pinpoint a particular property name or check the value as it is stored in the object. Certain datapoints (Roll20 IDs, recognizable hex color strings, and token marker names) are formatted to have a hover tip providing you more information very quickly. Also, the Roll20 IDs that are present in the output are also paired with a link to let you pull up that object in Inspector for a for detailed examination. If, on the other hand, you get a number of returns for your search criteria, they will be presented by category of the object. For instance, the command line: !about --Kraang the No Idea Is a Bad Idea Leader Might produce a return for a character going by that name, as well as all tokens representing this super-progressive character (and thus sharing a name). Extended Returns Some items are related to each other in the game even though they might not show up on the initial property panel as directly attached as a javascript property. You will see these returns represented in the returns panel as buttons at the bottom. They include such relationships as attributes, abilities, repeating lists, or tokens for a character, characters for a player, tokens for a page, etc. Each of the buttons has a hover-tip to tell you what it represents, if the chosen icon is not clear enough. (See  TextFor , for more information) Return Types For the most part, the returned types represent object types in a Roll20 game. In an effort to present more information, Inspector deviates from this in one or two places. First, there is no discrete Roll20 object for a repeating  list , nor for  repeating  as an object type separate from an  attribute , nor is there a foreign-key-style relationship between a list and an entry on that list, nor between a list entry and the various sub-attributes that are a part of that entry (the relationship is a bit more complex than that). Similarly, there is no object-level distinction between a  player  object who is a GM versus one who is not. All of this data can be determined, however, and Inspector is built to allow you to flow between these related objects. Argument Types You have a few options for what to use in an argument. And since every argument produces a different panel of returns, they need not be related. General Text Text not recognized as one of the special arguments below will be used as search criteria across all objects in your game. Inspector will look for matches in the  id ,  name ,  displayname  (for players),  title  (for jukebox tracks), or  text  (for text objects) properties. (At this point, your supplied criteria must match fully what is in the property. Perhaps at some point in the future Inspector will be able to perform partial matches.) Message Use message or msg to look at this message. !about --message This is helpful if you want to see the way a message comes structured from Roll20, including any rolls or selected tokens. Remember, messages are handed off from script to script, so by the time Inspector sees the message it may have been altered by other scripts (especially metascripts). Selected Use selected to specifically see the data in the message object for any selected tokens. !about --selected Rolls Use any of  rolls ,  inline , or  inlinerolls  to view the inline rolls that are a part of the message. The rolls can be included almost anywhere in the command line, from just after the script handle to after the  rolls  handle: !about [[2d20kh1]] --rolls  !about --rolls [[ 1d[[2d20kl1]] ]] It also works to put an inline roll as the argument, itself, to see that roll expanded in its own panel: !about --[[2d20kl1]] State A game's state is where data that requires tracking between sessions or sandbox reboots is stored. It is the most permanent storage available to a script, so scripters often use it for user preferences, script configurations, or caching. You can get a look at the state (or component parts of it) by using the word  state . !about --state Depending on the number of scripts you have installed and how much the developers responsible for those scripts have utilized the state object, you might have quite a sizable return. In that case, you might wish to see a smaller section of the state. You can use dot notation to drill down to properties attached to the state object, narrowing the scope of your returns: !about --state.Inspector !about --state.Inspector.settings Type The keyword  type  gives you the opportunity to return all things associated with one or more Roll20 object types. Include the types you want to search for after a space, and separate each with a space: !about --type player !about --type character token For these searches, you will very likely have more than one return, so you will see the panel of categorized results showing the objects Inspector found. Use the  View  button to view a more detailed breakdown of an individual object. The following types are recognized: ability attribute campaign card character custfx (also: fx) deck graphic hand handout jukeboxtrack (also: track) list macro page path player repeating rollabletable (also: table) tableitem (also: item) text token TypeFor The  typefor  keyword lets you build object lists from objects that are related by game context, if not directly by property attachment. This could include tokens on a page, or characters for a player. The full set of  typefor  combinations is given, below. To use them, begin the argument with  typefor , followed by the sub-parts  for  and  type  set equal to the appropriate value: !about --typefor type=player for=Start !about --typefor type=token for=Kraang Gifter of Office Mints The first example asks for players currently on the Start page. The second example asks for tokens associated with the ever-more-benevolent Kraang. For certain combinations (such as entries on a repeating list), a third argument, list, is required: !about --typefor type=repeating list=traits for=Kraang Bringer of Bagels It does not matter in which order the sub-arguments come. The  type  sub-argument should be singular, and the  for  sub-argument should be a way to identify a parent object. TypeFor Combinations The following combinations will work in the typefor argument: For a character:  * attribute  * ability  * token  * list For a page:  * token  * graphic  * path  * text  * player For a player:  * character  * token  * macro  * handout  * hand  * card For a table:  * tableitem For a list:  * repeating (requires list sub-argument) A Note About Hover Tips As mentioned, Roll20 IDs, hex color strings, and token markers are hoverable items. If the tip is attached to an object's ID, it will contain the most relevant information for that object. Colors and markers will show a preview. Token markers are only detected in the detailed look at a token (in the  statusmarkers  property), and in the Campaign detail in the  _token_markers  property. Configuration Use the script handle  aboutconfig  to change script settings. As of this release, script arguments are not case-sensitive. Booleans Boolean properties are set to  true  if they are set to any of the following:  true ,  t ,  yes ,  yep ,  yup ,  y ,  + , or  keith . Any other value passed will evaluate as false. playersCanUse Because Inspector offers a way to glimpse game or campaign data not otherwise easily viewable, it comes pre-configured to only allow GMs to use it. You can allow players to use the script by setting  playersCanUse  to true: !aboutconfig --playerscanuse=keith playersCanIDs If the players can use the script, can they search by ID? Honestly, this one is less useful given the amount of information that is presented even in hover tips, so I would suggest relying on the  playersCanUse  setting more than this one. However, if you find a case where you would like your players able to search only by name/text/title, you can control access with the  playersCanIDs  setting: !aboutconfig --playerscanids=false
1666797708
timmaugh
Pro
API Scripter
Update: Patched Messenger Thanks to Keith for both catching that I hadn't linked to the Messenger companion script that Inspector needs, and also helping me realize I had the wrong version of Messenger uploaded! I've updated the repo with the proper version, and updated the post, above, with the links.
1666802571
timmaugh
Pro
API Scripter
Update: 1.0.0.b2 (Beta-2 Release) New version is at the same link in my repo. Thanks, again, to Keith for finding this one. FIXED: GM Notes with special characters (like an emdash) would break the parser and cause a sandbox crash.
1666839188

Edited 1666871486
timmaugh
Pro
API Scripter
Update: 1.0.0.b5 (Beta-5 release - requires Messenger v1.0.0.b3, which is also being released) New version is at the same link in my repo. Keith continues to find good suggestions and/or bugs. (There's a reason he's listed as a positive boolean response in the script!) CHANGED : State query will now produce a panel of the various keys attached at the root level of the state object rather than parsing it into a well-formatted JSON output. Large states were timing out the sandbox and causing it to crash. Users who run: !about --state ...will now see something like this (state objects will be different depending on the scripts you have installed and the circumstances of your setup): CHANGED : Messages from Inspector are now set to not archive to your chat history.
1666871229
David M.
Pro
API Scripter
That State inspector update looks pretty handy! Though it does rob us of the joy of logging and sifting through the console during development ;)
1666881243
timmaugh
Pro
API Scripter
I mean... no one is saying you can't ALSO sift through the console. I guess. d=(ᵔᴥᵔ)=b
1669127180
timmaugh
Pro
API Scripter
Update: v1.0.0 (1-Click Release) Inspector is in the queue to be merged into the 1-click with this week's (22 Nov 2022) pull request, as is the supporting script of Messenger.
1669129651
keithcurtis
Forum Champion
Marketplace Creator
API Scripter
Hmm. It occurred to me that a handy feature to have would be a way to export and import the state object. One of the hassles of starting a new game is to reconfigure all the script states. Would something like this be feasible, or even a good idea?
1669135004
timmaugh
Pro
API Scripter
That is definitely feasible. I had a recent issue with a game's state getting filled up, and it occurred to me that Inspector, with its existing presentation of the state, could easily offer a way to "clean up" a state that's littered with the detritus of old scripts. Rendering the state to a... well... state... that is exportable and transferable to a new game is a straightforward extension of that functionality! Let me get that worked up!