[Script] RollStats - looking for feedback

EDITED TO REFLECT UPDATED SCRIPT

Ever feel like you constantly are the one rolling nat 1s when everyone else gets a nat20?  I initially wrote a fairly basic script to keep track of that with limited output.  After finding another version of this concept in a branch from 7 years ago from manveti I've gone ahead and merged the two creating a script that has the interesting output options while working and using more updated best practices.

Note - the below code block is updated with each version of the script:

Current Version - 1.1
no command is necessary to start collecting stats - this will happen automatically after install
Usage:			    !rollstats [options]
---Display Modes---
  -f, --full:		    show full stats for specified die
  -l, --leaderboard: 	    show player leaderboard
  -o, --overall:	    show overall stats
---Options---
  -c, --chat:		    show stats in chat (default: whisper to you)
  -d <N>, --die <N>:	    show stats for specified die size (default: 20)
  -g, --global:		    show stats for all players (default: show your stats)
  -h, --help:		    display this help
  -p <P>, --player <P>:	    show stats for roll20 userID P (default: show your stats)
  -s, --session: 	    show stats for current session (default: all time)
  --clear:		    clear collected stats (GM only)

Examples
!rollstats -l               whispers leaderboard d20 stats for all players
!rollstats -o               whispers summary die stats for all your die rolls
!rollstats -f -d 8          whispers full stats for your d8 rolls to you
!rollstats -f --die 8       same as above
!rollstats -l -c            sends d20 leaderboard to all chat
!rollstats -l -s -c         sends d20 leaderboard to all chat only for rolls this session, not all time

The testing I've done is covered in this doc.  Highlights of what to look out for - would appreciate insight into how / if any can be fixed:

• -p, --player only works with roll20 user ID (ex: 2824773 for me), display name does not seem to find a user properly
• NPC dmg rolls (5e, default) seem to always roll critical dmg even when it is not used - aka a 1d12 Greataxe will always roll 2d12 even if neither attack roll is a crit, it just doesn't display the second roll
• this does not break anything, it just inflates the die rolls for anyone rolling off an NPC sheet
• FATE dice record as a d3 but don't really reflect properly in average, etc... - not really worth using for FATE

https://gist.github.com/thedoe/f5bfa9bf938109df382b274476565510

How do you use it?

I tried installing both scripts and the first did nothing, the second throws an error the second I hit save and it restarts.  "RollStats is already declared".  

How do you use it?

Excellent point - added some basic usage comments to the top.  Essentially

• on install it will automatically begin collecting stats for each player (based on player ID) - no action required
• players can use the "!rollstats show [die]" command to see their own stats - currently sent to global chat
• die values are scrubbed of any non-numerics so d20 and 20 would both work with a default of 20
• GM can use "!rollstats clear" to clear the stats anytime
• this uses the playerIsGM() utility function which, at least right now, appears to return "false" no matter what in my

Also edited the original post to include a code embed since the gist link wasn't pulling it in automatically like the sticky [Read First] post mentioned.

Either the bogus paste from your first script you linked broke my sandbox or you are using a command already in use by one of my other scripts installed.  It keeps telling me RollStats is already declared after installing it.  Theres also a red error.  

I tried installing both scripts and the first did nothing, the second throws an error the second I hit save and it restarts.  "RollStats is already declared"

I'm not sure what you mean by "both scripts" - there is only one.

I believe the "RollStats is already declared" might be if you have two separate scripts with the above code in it.  That would throw that error because the const RollStats exists in both script declarations (since they are the same) - I just verified getting that error by trying to create two scripts with the same copy+paste code from above.

As for "doing nothing" you won't actually visually see anything happening after install.  Perhaps on initialization it makes sense to have a visual cue sent to the GM that die statistics are being generated beyond just the log message - I can definitely add that.  If you do some rolls (inline, /roll, or via the toolbar) and use "!rollstats show" you should see it in action.

Chris M. said:

I tried installing both scripts and the first did nothing, the second throws an error the second I hit save and it restarts.  "RollStats is already declared"

I'm not sure what you mean by "both scripts" - there is only one.

I believe the "RollStats is already declared" might be if you have two separate scripts with the above code in it.  That would throw that error because the const RollStats exists in both script declarations (since they are the same) - I just verified getting that error by trying to create two scripts with the same copy+paste code from above.

As for "doing nothing" you won't actually visually see anything happening after install.  Perhaps on initialization it makes sense to have a visual cue sent to the GM that die statistics are being generated beyond just the log message - I can definitely add that.  If you do some rolls (inline, /roll, or via the toolbar) and use "!rollstats show" you should see it in action.

Your first post sent me to a github link with a very short script, I pasted that into the sandbox and it did nothing.  I deleted it then got your new script.  I'm guessing my sandbox is fubar from that first post you posted?

Your first post sent me to a github link with a very short script, I pasted that into the sandbox and it did nothing.  I deleted it then got your new script.  I'm guessing my sandbox is fubar from that first post you posted?

The github gist link is still in that post and if you take a look at the revisions you can see the only thing I added after that post were the 4 comment lines on usage - no additional executable code or anything that would "fubar" the sandbox should exist in either.

As for the error it could be a conflict with some other script that is potentially using the same variable name - RollStats - I am.  Do you have one that does something like generating statistics (hp, etc...) for mobs?  Trying to think of something that would logically use that type of variable naming convention.  I definitely have this running in a test game with no other scripts besides the "APIHeartBeat" script while I was writing and running tests and no conflict exists.

This is what I have installed

Well I can't run the test for the script in a blank session.  Can we search their scripts for the word rollstats or something, is there not an easy place to look at the one clicks raw data without having to google every single one?

I opened up the first two manual scripts installed before yours and they both were exact replicas of your script.  Now I know sure, I could be a moron on the internet and sure, I maybe fatfingered it I guess?  Twice?  I make a new session with this many scripts weekly almost.  I really do not remember fat fingering anything and I know for a fact when I pasted it was a blank dang window and I even left the damned name "untitled.js" both times so I really question wtf is going on here but after fixing all my previous manual scripts your script works.  

Searching the roll20 git repository I actually found an old script there (last checkin 7 years ago) with the same name and, remarkably enough, the same goal of my script.  Makes sense with the name clash at least.  Odd as well is why it doesn't show up in the "Code" portion of git search but only in "Commits".

This script isn't in the Roll20 API Script Library (why I thought one was necessary - no idea if this old one works) and I don't see it in your screenshot either so I'm still quite confused as to why you are receiving an identifier clash.

edited to add screenshot showing no "code" with RollStats despite there appearing to be some

Yeah that's definitely really weird as to why an almost blank script showed up for you multiple times.  I definitely only saved the gist initially with the code once it was working successfully on my test game.  I would never post code not having done initial validation first.  It's also one of the big reasons I used the template from TheAaron's post as a basis in an attempt to ensure I was following best practices and minimizing any conflict.

You are clearly competent at running, installing, and using API scripts so I'm def not questioning that - apologies if it came off that way.  I am just as confused as to how it could have happened.

From the sounds of your last post things are not erroring for you any more which I'm very happy to hear - correct?  The last thing I would want is to have my code cause any issues for your game and I want to be sure to troubleshoot until you are set.

All set, it seems to be working fine.  Default really is fine to use honestly for output.  I mean if you wanna put more work into it you could do the fancy stuff thats out there but Default is a great table result viewer really.  If you were to go with another way to display I'd say try and do a bar graph setup maybe?  Something like apiheartbeats display thing?

Very glad to hear that!

Honestly more disappointed in myself for not having found the old script from the start. It's not in the Roll20 drop-down but wish I had checked the full GitHub repo. Hilarious how much of the code is almost exactly what I wrote down to the name - although makes sense given it is trying to accomplish the same thing. It likely makes sense to look into updating that rather than adding to mine.

+1 to the bar chart view - I had built a script originally that passed the chat log and ran charts in Google Sheets which were always nice.

Thanks again for taking a look and apologies that it somehow caused a bunch of confusion in your day!

My only suggestions so far is, possibly have the option to whisper it to myself instead of to everyone, also is there a way to drop a character ID in to get that players details while they are offline or something or if a DM wants to keep the button for their own use to show to the players?

I have the following error when trying to clear stats.  I am the GM, I own the session, I am logged in as a DM:

Thanks again for all the feedback!  Def agree those would make the script a lot more user friendly.  Looking through the old API script I found during our conversation it has a number of those features already built in.

Given the existence of that script I am going to shift from writing mine from scratch to branching the existing code, validating it still works, and potentially updating some of it to be more in line with the more standard things in TheAaron's template (like versioning) so that it can ideally be included in the Roll20 API dropdown.  Especially since so much of our code is similar I don't want to reinvent the wheel and also be sure that those who contributed to the earlier script continue to get credit.  I'll post a new thread looking for feedback once that is done.

I have the following error when trying to clear stats.  I am the GM, I own the session, I am logged in as a DM:

Did some more digging - the API Utility Functions docs don't call out the need for supplying a player ID but after digging around other scripts in the github repo it looks like that is necessary.  Makes sense but not something I included in my initial script - I updated the gist for posterity but, as noted above, will switch to branching off the existing API script.

Chris M. said:

Thanks again for all the feedback!  Def agree those would make the script a lot more user friendly.  Looking through the old API script I found during our conversation it has a number of those features already built in.

Given the existence of that script I am going to shift from writing mine from scratch to branching the existing code, validating it still works, and potentially updating some of it to be more in line with the more standard things in TheAaron's template (like versioning) so that it can ideally be included in the Roll20 API dropdown.  Especially since so much of our code is similar I don't want to reinvent the wheel and also be sure that those who contributed to the earlier script continue to get credit.  I'll post a new thread looking for feedback once that is done.

I have the following error when trying to clear stats.  I am the GM, I own the session, I am logged in as a DM:

Did some more digging - the API Utility Functions docs don't call out the need for supplying a player ID but after digging around other scripts in the github repo it looks like that is necessary.  Makes sense but not something I included in my initial script - I updated the gist for posterity but, as noted above, will switch to branching off the existing API script.

Ok, I really think you have a good script concept here.  Players and DM's honestly are very superstitious and I think it is a really cool capability to view your track record.  The only other thing I could think of for more feedback is maybe have the odds for a DC pop out too if we give a different command, I know theres a way to find it on our own but players often are not math wizzes.  Have it ask for our mod, then ask for the DC, and BAM percentage of success pops out.  You could fancy up the template but Default really does suffice.  Its a table view template and works on all sheets and I'm totally fine with it.  

Ok, I really think you have a good script concept here.  Players and DM's honestly are very superstitious and I think it is a really cool capability to view your track record. 

Thanks!  The roll stats is def a concept I want to include in my games - +1 to the superstitious, no comment about myself haha!

The only other thing I could think of for more feedback is maybe have the odds for a DC pop out too if we give a different command, I know theres a way to find it on our own but players often are not math wizzes.  Have it ask for our mod, then ask for the DC, and BAM percentage of success pops out.  You could fancy up the template but Default really does suffice.  Its a table view template and works on all sheets and I'm totally fine with it.

This is a really interesting idea.  I think keeping it as a separate API makes more sense as the roll statistics are more of a passive tracking thing that doesn't make any change to live play vs the DC tracker.  Personally it's not one that I would use as I really enjoy not doing the math most of the time.  I personally don't like the math driving most of my decisions but instead a feeling of what my char might do in the moment.  Of course they will tend towards the things they are good at but I don't like thinking "45% chance, no I won't do it even if it contributes to a good story".  That's just my personal preference though :)

Hi all,

I installed the version you posted in your first post, and it works fine.

I tried the version of 7 years ago, because it seemed to have a little more functions, such as by-player stats.. but when i try the variuos possible commands, nothing at all happens.

I must say that i'm not really understanding the different patches, or the commandshell thing... Is there a full version, that would be working with the functionnalities that manveti implemented on this ?

Thanks for anyone's help.

Thanks Lionel for asking!  I'll update the top post to try and add clarity.

I'm currently merging my initial script with the one from 7 years ago.  As you mention there was a lot of great output functionality in that I hadn't included in my first pass and I want people to be able to take advantage of that.  I also want to ensure the original contributors continue to get credit for their ideas by including them in the docs.

Right now things are exactly as you stated - my originally linked script works but is fairly basic, manveti's script does not seem to work.  I will post a new thread once my merge is complete with a script that works and has all the functionality of manveti's script.  Likely timing is this week but depends on work, family, etc...

Hi all - based on the rule of "one thread per script" I've gone ahead and updated the original post here to reflect the new script.  I took the display options from manveti's original script I found in the 7 year old branch and added them to the base script I had built out.

Everything should be working and I would love thoughts + feedback prior to submitting this to be included in the Roll20 API dropdown.  As always while I ran testing (see test log) I recommend not installing this on a live game right away until multiple people have been able to play with it in a sandbox.

Chris M. said:

Hi all - based on the rule of "one thread per script" I've gone ahead and updated the original post here to reflect the new script.  I took the display options from manveti's original script I found in the 7 year old branch and added them to the base script I had built out.

Everything should be working and I would love thoughts + feedback prior to submitting this to be included in the Roll20 API dropdown.  As always while I ran testing (see test log) I recommend not installing this on a live game right away until multiple people have been able to play with it in a sandbox.

Did you solve the inability to reset the stats?  Or is there another way to do it like uninstalling and reinstalling?  Thats my biggest issue cause I want fresh stats every session but it gave me the error above when I tried to reset them.  I'm the DM, on my DM account, in a session I own.  

Did you solve the inability to reset the stats?  Or is there another way to do it like uninstalling and reinstalling?  Thats my biggest issue cause I want fresh stats every session but it gave me the error above when I tried to reset them.  I'm the DM, on my DM account, in a session I own.

Yup, it was a problem of not passing in the player ID param in my initial script.  This is what I see when I use "--clear" as GM from my test.  Can you double check that you have the new script (it should have the usage guide with the updated display options).

You actually won't need to clear the stats per session either.  The script keeps track of stats both long-term and for the life of a game's API sandbox.  Normally that also equates to a single session unless you leave the game up and running w/ someone logged in the entire time between or if the sandbox has to restart mid-game.  To see only the session stats you would use the "-s" or "--summary" flag.

I can get the awkward single dash options to work but the traditional double dashes sometimes aren't working, maybe I'm not understanding the syntax.  What is the syntax for double dashes if I wanted to check D12's?

Arf On my side, nothing happens, whatever i type in, i always get this message :

(From RollStats):
No stats have been collected for this player
Use !rollstats -h for help

And this even if no player or token is selected... and even calling another command such as chat, or global or whatever i always only get the same message.

But bow i've erased the previous version i tried (your script version) and now i cannot find it anywhere as i can find it back anywhere????

snif

Apologies for delayed responses - was away for a couple days.

I can get the awkward single dash options to work but the traditional double dashes sometimes aren't working, maybe I'm not understanding the syntax.  What is the syntax for double dashes if I wanted to check D12's?

Thanks for calling out the double dashes acting oddly!  I was able to find a bug specifically with --die when it looks for the numeric die value.  The -d option does work correctly - will fix --die and update the gist with a new minor version number.  I think it's also a bit confusing having the detailed stats also correlating with specifying the die value that might be used in the leaderboard output.  I'm going to separate that out so display flags and option flags don't have any overlap.

Ah I think i understood ! as it was a new session of sandbox, no rolls are registered. But i thought readibng your last post, chris, that stats were recorded throughout all sessions...

Stats are kept both at the session (aka sandbox) level and long-term.  I had to choose between the old long-term variable used by manveti or the variable I came up with.  I decided on manveti's just in case someone had been using that version my new code would continue to work if they upgraded to the dropdown with their collected stats.  Since we only had you and DM Eddie test the first version I felt like that was the best choice.  Moving forward I won't be changing the permanent stats name so you should have stats both for the session and all-time after install (or the last --clear).

Found the problem with the "--die" and "--player" options - turns out I was expecting a null result from a function if a value wasn't found when it was actually -1.  New version on gist is above:  Updating overall help in the first post as well.

All Updates

• fixed the "--die" and "--player" options not working properly
• -d <N>, --die <N> has been broken out as an option only, not a display mode
  
• -f, --full has been added as a display mode to show full stats for a die, replaces -d / --die to avoid ambiguity
• added try-catch blocks to minimize the possibility of RollStats crashing the API sandbox with an unexpected error
• thanks to TheAaron yet again as I've re-used their concepts on catching API errors and suggesting they are sent to me
• added additional validation and clearer error messages to the user

Updating to 1.1 will not cause your overall stats from prior sessions to reset.

This has been a fun script for my players.  They complain that they always Crit Fail (1) many more times than they Crit Succeed (20).  I've been able to run stats to disprove that.  As far as improvements, here are a couple I've actually considered spending some time to add myself if you don't.

1. Add a Criticals report that shows the number and percentage of D20 1s vs 20s.  
2. Add ability to dump out all the numbers to a handout, where it can then be copied and pasted into a tool like Excel for further reporting/analysis.  

Will

Will M. said:

This has been a fun script for my players.  They complain that they always Crit Fail (1) many more times than they Crit Succeed (20).  I've been able to run stats to disprove that.

So glad you are enjoying it!  We actually had some fun the other night where our GM had a run of really bad luck that turned a really challenging encounter into one that was much more straightforward.  It was really cool to see how bad the rolls were at the end while still being able to keep them hidden during the fight.

As far as improvements, here are a couple I've actually considered spending some time to add myself if you don't.

1. Add a Criticals report that shows the number and percentage of D20 1s vs 20s.
2. Add ability to dump out all the numbers to a handout, where it can then be copied and pasted into a tool like Excel for further reporting/analysis.  

Really like the idea of criticals information - I wonder how it would look incorporated in the d20 Leaderboard view vs a separate Criticals only view, will test both and see.

The handout is really interesting too - do you feel like there is something missing in the output you would want to see dumped into a handout, a certain current view that would work well, what are you seeing as the handout looking like?

Since I play Fate, I tweaked the script to be useful for fate rolls. Chris, feel free to take this code if you want to add it. I changed all the defaults from d20 to dF, so you might want to change them back.

It assumes that any roll where you roll 4 d3s is a Fate roll.

Enter --die f or -d f to get die results.

https://gist.github.com/birdbrainiac/9c88d1e20e3ab2009033a2c096b082d5

I did not realize I was running 1.0 instead of 1.1, but that said, I just updated, but I came here originally because I am experiencing an issue where only my rolls(the DM's) get properly caught every time.  I wonder if the issue is that their sheets do not include character names in their templates or that their represents as in chat sometimes is wrong?

I wonder if rolls from D&DBeyond are being captured? Or rolls from api scripts like ScriptCards?

My players all roll with their character sheet, and also the newest version of this script, the rollstats command only works for the dm.  none of their stuff says that stats have been collected for them.  

Apologies all, life got incredibly busy the past month.  Replies to everyone below:

@GiGs - amazing, thanks so much!  I knew nothing about Fate so really appreciate you adding that in - I'll incorporate it when I submit to git.

@Will M - D&DBeyond rolls are captured if the option for "Use D&D Beyond's Digital Dice" is disabled in beyond20.  When that option is enabled it doesn't actually perform a roll within roll20 - it simply prints the results of the roll in formatted view.  Since rollstats looks specifically for roll commands it does not parse these.

@DM Eddie - hmmm, that's definitely weird.  Out of curiosity what character sheet version do you use?  This has been tested (including tonight) via the "D&D 5e by Roll20" sheets, would be curious if other sheets process rolls differently.  Also what command are they using?

Hi Chris, my players have enjoyed using your script immensely but I received an error message when trying to post the player leaderboard into chat with the macro !rollstats -l -c 

The command worked perfectly earlier in the session, but after one player changed their character name I started to get this message, even after changing the character name back to the original.