ActivityTracker Files: My personal repo Version: 0.0.1 Abstract ActivityTracker is a customizable way to track events in a game, even when you're not there. Individual events can be enabled or disabled, and the entire system can be armed or disarmed to log the enabled events as they occur. The primary use would be for troubleshooting a given problem that your game might be having (to track the trigger of the problem to a particular event, allowing you to research which of your scripts are set up to take action based on that event), or for researching the structure of an object associated with an event (for instance, the message object associated with the chat:message event). Installation Copy the code from the above link into a new tab in your Script page, name the tab something meaningful (like "ActivityTracker"), and save it. When your sandbox reboots, you will get a message alerting you to restart your sandbox one more time: This is simply because the first time the script is installed, it is creating its footprint in the state object and then registering the event listeners. Rebooting the API will let those event listeners register at an earlier position in the queue of your registered scripts (giving them a better chance of catching the event before another script would do something to break your sandbox). Alert If ActivityTracker is armed (meaning it will track events for you), it gives you an alert message every time the sandbox is rebooted. ActivityTracker stores its log (including the associated objects for each event) in your game's state object, so it's important for you to know when your state object might be filling up with more and more logging. The alert message includes a button to "Disarm" ActivityTracker (preventing it from logging any event): Usage The basic command for this script is: !track That will bring up a config panel for the script. You can do pretty much anything else you want to do with the script from the config panel. (See Advanced Commands, below, for other options) Configuration The configuration panel lets you set many options for the script. As just mentioned, enter !track into chat to get the configuration panel. Available options include: Date format (for event date/times) Arming/Disarming Event enabling/disabling Color coding events Buttons You'll see buttons to let you do most of the typical things you'd want to do with the script. Defaults: set events and color coding to values as of first installation (see Defaults, below) Arm/Disarm: arm or disarm the script (you will only see one of these buttons, corresponding to the action you can take) Enable Event*: presents you a list of the currently-disabled events (those not set up to log); picking one will enable that event Disable Event*: presents you a list of the currently-enabled events (those set up to log), picking one will disable that event Enable All: sets all events to be enabled Disable All: sets all events to be disabled Event Color: presents a selection of all events, and prompts for a color to associate; valid color formats include 6 digit hex with or without leading hash (#ffffff or ffffff), 3 digit hex with or without leading hash (#000 or 000), or valid HTML color names (ie, lavender, gray, etc.) Date Format: presents a list of date formats to let you pick a region-specific format, or just one that suits your aesthetic Clear Log: Clears all entries from the log Report: displays the list of events (see Report Output, below) * - for the Enable and Disable buttons, the list is built at the time that the panel is output to chat. That means that if you disable an event, for example, and then click the same Disable Event button, you will see the same list even though in truth you've already disabled one of the objects. This is a limitation of having to work through the Roll20 chat interface. It hurts nothing to enable an already-enabled event, or to disable an already-disabled event. Defaults When it is first installed, ActivityTracker will be armed, but will only be set up to track three events: change:player:_online chat:message ready Two of those are setup to be color coded for easier location in your output (chat and ready). Also, the Date Format is set up to be "mmm dd yyyy". If you ever reset the script to default settings, it will revert to this state. Report Output To see the Report from the logged events, you can click on the Report button from the config panel, or you can simply run: !track --report all (see Advanced Commands for more options) The report will show an entry for every event for which it was enabled to track (that is, it won't track the events you tell it to ignore). Each entry will have a pair of buttons, OBJ and PREV. These represent the objects that Roll20 passes along with the events. For a chat:message event, there is only the message object, which would be under the OBJ button. Other events, like a token change, would have the previous state of the token under the PREV button, and the new state under the OBJ button. If an event has an associated color set up in the script's configuration, you will see those events in that particular color. Above, you can see that the ready and chat:message events have associated colors (default colors shown). If there is no color designated, the rows alternate between white and a light gray. Each row will have the date and time of the event (which can be formatted in the script's configuration), the event that was tracked, and then the buttons to link to the current/new and previous objects. Object Information Clicking either object button from the Report panel will display information about the chosen object. The output will include the date/time of the event, the type of event, and the object you are viewing (OBJ or PREV). Here is a sample of a message event's log entry, showing the structure of the message: (Note: although ActivityTracker registers at meta-speed, other meta-scripts already installed will register first, and so can alter the message before ActivityTracker gets the message object; you can see that, above, in that ZeroFrame has added certain properties to the message object already. If none of that means anything to you, don't worry about it.) Every Object Panel has a button to go to the opposite object (to view the PREV object if you are on the OBJ obj, or vice versa), as well as a button to view the Configuration Panel again. Caveat: User Generated Events Scripts that alter the game do not generate or emit events the way that user-generated actions do. That means that the actions taken within a script will not be logged. The log will show the user's intent to send the command line to a script (for instance, calling TokenMod), but it will not track the token changes taken by TokenMod. Advanced Commands Enable Multiple Events You can enable multiple events in one go. This utilizes the --set command. Replace all colon characters in the event with pipes, set the event equal to 'true' or 'false' (no spaces), and separate events by a space: !track --set chat|message=true ready=true add|card=false It can be combined with other arguments. See Color Code Multiple Events for an example of this. Color Code Multiple Events Similarly, you can color code multiple events in one command. This utilizes the --color command. Replace all colon characters in the event with pipes, and set the event equal to a valid hex color (#d9A, #ffffff, lavender, gray, etc.). Again, don't include spaces around the equal sign, but separate events to color code with a space: !track --color chat|message=#ffeee1 ready=cadetblue It can be combined with other arguments, for instance enabling or disabling events at the same time: !track --color chat|message=burlywood --set chat|message=true change|attribute=false Report Recent Events The --report argument takes either a valid number or the word 'all'. !track --report all If you include a number, it will report that number of the most recent events: !track --report 10 ...reports the last 10 events. Other Commands Defaults !track --defaults or !track --restore Clear Lo g !track --clear or !track --reset Arm/Disarm !track --arm !track --disarm
