Inspector FILE LOCATION: My Personal Repo and 1-click 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
