Adds a new sidebar for rolling and managing dice roll expressions.
This script adds an advanced rolling sidebar to the Crawler's Companion site used for the RPG Dungeon Crawl Classics.
First you must install a userscript manager extension in your Browser. This script has been tested with the extension Violentmonkey in Firefox. To install it for Firefox, click here.
Next you must install this script in the userscript manager. You should be able to install the script using the install button from Greasyfork. However you can also add it manually to Violentmonkey by:
Finally, load the Crawler's Companion. Your userscript manager should automatically run this script once the page has finished loading, and you should see a new button at the titlebar of the left sidebar (where you normally would find the dice roller).
Click the "Roller" button at the top of the left sidebar to bring up the roller. Use the X at the top right of the roller page to close it. Make sure to do that before trying to click a different section of the left sidebar.
The advanced roller page consists of two main sections.
The top section is for entering a new roll and saving it to the saved rolls. It can be used to perform one-off rolls, or to create and save a roll that you will use regularlt.
The bottom section contains saved rolls along with a name for the roll so that you can find and roll them at any time.
The top section consists of a text area where you can type in a roll expression. Clicking 'Roll' will perform that roll and write it to the roll log so other people can see the roll. The 'Test' button performs the roll but displays it just below the section and does not add it to the roll log, so that you can test out and modify rolls until you are satisfied with the format. If you enter a name for the roll and click 'Save' the roll will be saved to the 'Saved Rolls' section and will be available the next time you load the Crawler's Companion.
The bottom (Saved Rolls) section lists rolls that have been saved. It displays the name and roll expression for each roll, along with buttons. The 'Roll' button performs the roll and broadcasts it to the roll log. The 'Delete' button deletes the roll. The 'Edit' button fills in the name and roll expression of that roll into the top section so that you can modify the roll. When you are happy with the modifications you can click Save to update the saved roll.
The the bottom section, the filter input box is used to perform a fuzzy search over the names of the the saved rolls. If the filter is not empty, only the saved rolls that match the filter are displayed.
In the bottom section is a button labeled 'Raw'. Clicking that button changes the view to display a JSON document that describes all the saved rolls in one document. If you change the document and click 'Update' the changes you made are applied to your saved rolls. The JSON document cna be used to export and import your rolls: you can make a copy of it and paste it to a file or document as a backup of your saved rolls, and later restore it by pasting it to this same textbox and clicking 'Update'. Click the 'Cooked' button to go back to the regular view.
Roll expressions consist of sums or differences of terms. Informally, the grammar is like so:
TERM +/- TERM +/- TERM ...
where +/- stands for either + or -, and each TERM stands for an allowed term. Terms are a dice roll expression or a non-negative number, with an optional label enclosed in aquare brackets, and an optional block of Javascript code enclosed in double-curly-braces. So one of:
DICE
DICE [LABEL]
DICE {{CODE}}
DICE [LABEL] {{CODE}}
NUMBER
NUMBER [LABEL]
NUMBER {{CODE}}
NUMBER [LABEL] {{CODE}}
where DICE stands for a dice roll expression, NUMBER is a number, and LABEL is a general string that contains anything except the characters '[' or ']', and CODE is a block of Javascript code that does not contain '}}'.
A dice roll expression is a standard basic RPG dice roll, for example 1d20, 2d6, 1d4 or similar. So an example of a full expression is:
1d20 [attack] + 1 [str] + 3
The CODE block is intended to allow modifying the calculated value of the term it belongs to. For example, if the term was simply '5' the code block can be used to modify it to another value like '0' when the roll is executed. The motivation for this was the Warrior and Dwarf Deeds Die terms: the deeds die rolled as part of the attack roll is also used for the damage roll. However it is general enough to be used for other purposes as needed.
The Javascript code blocks have access to a set of functions and variables:
The variable val contains the normal value of the term before the code is executed. For example, for the term '4' val would be 4. For the term '1d20' val would be the value of the random roll, for example 5.
The function set(name, val). This function sets a variable with the name name to the value val.
The function get(name, val). This function returns the value of a variable previously set by the set function. If there is no variable set with the specified name, undefined is returned.
As an example, here is how you can define an attack roll that saves the value of the deeds die, and a damage roll that uses that value:
1d20 [attack] + 1d5 [deed] {{set('deeds', val)}}
1d10 [damage] + 0 [deed] {{d = get('deeds', val); if (d !== undefined){return d} }}