Hidden Roll Messages


CODE: https://github.com/Tran-Phillip/roll20-api-scripts/tree/Hidden-Roll-Messages-v1.0.0-stable/HiddenRollMessages

Hey guises! 

I recently grinded through Disco Elysium over the weekend and one of the coolest features I thought was at certain points in the game the game would secretly roll a check for the player and send them information if the roll succeeded. This information could be anything from important story information to flavor text. Overall it just made the world feel a lot more real. 
Now, I was thinking about how to do something like this during a campaign and it's seems troublesome. The DM would have to stop what they were doing, ask a player to roll the dice, then whisper them the message. This would slow the pace of the game down and led into a lot of wasted time rolling, especially if the DM wants to use this system like how Disco Elysium uses it to increase world-building and role-playing. Like, rolling every time you want to give background information to players who have a high History stat would get old real fast. So here is my take at a solution. (see screen shots in the README on the github repo) 

How it works


The plugin allows users to create special handouts ([HRM] handouts) that contain JSON data in the 'notes' portion. 

The JSON is formatted as 

{
   "attr": <string: name of attribute to roll>, 
   "pass": <integer: threshold for successful roll>,
   "on_pass": <string: message to send if the check is successful> ,
   "on_failed": <string: (OPTIONAL) message to send if the check fails> 
}

Now when the handout is deleted (or the <!hrm play> command is called), the plugin will parse this JSON information, and make a roll. The roll is defined as 

roll_result = randomNumber(dice_sides) + (value of the "attr" specified in the JSON)

dice_sides is configurable (by default 20).

Then, it will message all players who passed the roll with the <"on_pass"> message.

note: the attribute specified in "attr" MUST BE exactly how it's defined in the "attributes and abilities" section of your character sheet. 

How does this work if rolls are calculated differently?


So the above default configuration works great for DnD, but what about for systems like Gumshoe or Call of Cthulhu (where this plugin would be even more beneficial) where the roll results are based on the character skill instead of a dice roll, well because dice_sides is configurable you can set the set this value to 0, thus the roll will be solely dependent on the "attr" value specified in the JSON. 
There is some flexibility to this system, but unfortunately my naming convientions might make it tricky to think about what to change haha.

Usage


To create a [HRM] handout, create a new handout and simply add our HRM_identifier (configurable) to the start of the name of the handout. 
By default the value of HRM_identifier is '!!!'. Then in the 'notes' section, add the JSON information as specified above (keep the exact name for the keys please) 
Example for a DnD campaign:



The plugin will tell you if the [HRM] handout was successfully created. If it wasn't, it was probably because the JSON put in the 'notes' was invalid. 

Once the [HRM] handout was successfully created, deleting it will execute the hidden roll! 

if you don't want to delete it, you can also use the api command 

!hrm play <Name of the handout w/o the [HRM] tag>


Note: The plugin only rolls for characters that ARE NOT controlled by the GM. 


API commands


The plugin is mostly manipulated by creating and deleting handouts, but there is one api command you can use 

!hrm play <name of handout w/o [HRM] tag> -> executes the hidden roll. Use this if you want to execute a handout without deleting it.

Use Cases / more examples


Here are some use cases I thought up while making this! The following is assuming you are the DM. 
Note for these examples, when you see the underlined word that is when you would delete the corresponding [HRM] handout and execute the hidden roll


1) You are starting the campaign by giving some background about the world. 
"The city of Redania was a peaceful province southwest of the Alirgian border, it was the leader in technological, medicinal, and economic advancements ... at least, until the war
The corresponding handout would look like  

  1. {     "attr": "history_bonus",     "pass": 7,     "on_passed": "The Redania / Tellsar War lasted betwwen 1200 RD and 1232 RD. It was the largest land war waged up to do within the Rein Kingdoms and had the highest casualty count of any war before then. }    


2) The party is interrogating the owner of a shady business. You are roll-playing the business owner
" I don't know why you're here! I've heard nothing 'bout no missing scallenger eggs! Now get out of my shop!"

The corresponding handout would look like: 

  1. {     "attr": "perception_bonus",     "pass": 14,     "on_passed": "Sjalf's eyes dart around the room, as if he's looking for an escape route." }    


3) The party is walking through a Wizard's tower. The are in the middle of a battle against said Wizard. 

You as the DM want to hint at the kind of magic this wizard will use. 

The corresponding handout would look like: 

{
    "attr": "arcana_bonus", 
    "pass": 20, 
    "on_pass": "You notice above the wizard's mantle is a Photonic Resonator, a popular catalyst for Frost magics", 
    "on_failed": "You notice a strange object on the wall, however you can't identify it"
}

Common Issues / Mistakes


1) I deleted the handout, but there was no success or fail message! 
     - Are you sure you have a character in the session that is not controlled by the DM?
2) My handout keeps getting renamed INVALID JSON HANDOUT

     - ...is your JSON valid? One of the most common errors I see is that they have a extra comma at the end
3) I always fail the hidden roll! 
    - Is the attribute specified in the JSON EXACTLY like how it is the "attributes and abilities" section of your character sheet? If an attribute is misspelt or does not exist, the roll will always fail. 


Last Words


Whew that was a mouth-full. I hope you guys like the plug in and do some cool stuff with it! This is my first time every posting a script to this website so any concerns of criticisms are always appreciated and apologies if I broke some etiquettes of forum posting! I am new at this. 
If you have any feature requests or bug issues I'd love to know! You can contact me through this post or open up a Issue in the github repo! I pay attention much more to github than fourms btw so if its something you want addressed immediately I'd go there.

Best Regards All, 
Phillz