Dice Roller Features:

• You can roll Sets of rolls.
  6[3d6]
• You can drop lowest rolls from the total.
  4d20~1
• Reroll your rolls: You can use < and > (Greater Than) (Less Than) to make results less than and/or greater than a value. If a roll value does not meet your criteria it will be rerolled until it does.
  1d20>10
• You can use Math operators: * / + - ( )
  6d6-8*2d10+10d4
• Use parenthesis to control your dice roll result.
  ((2d6-3)*2)+10
• Use conditional logic to control your rolls with IF...THEN...ELSE...END.
  IF 1d20+5 >= 20 THEN 1d20+5 ELSE 3d6+6 END
• A roll can have more than one roll in it, so that more than one separate roll can be made at a time. Rolls are separated by a Semicolon"
  3d6 ; 5d8 ; 1d20+5

Dice Roller Results:

• Dice Roll result display can be shown as integers or real numbers. You may specify the number of decimal places to display in the Preferences. If you choose zero decimal places numbers will be truncated. Also, if a roll result contains no significant digits after the decimal, the decimal will be removed. (eg: 15.000 would display as 15)
• You can control the actual numbers in your rolls by using the Round, Floor and Ceil Dice Functions.
• Use may use comments in your dice rolls to add a text message in the actual roll's output.
• Play sounds for dice rolls. This will override the default sound and can play any sound file in your CrystalBallData Sounds folder.
• The roller automatically totals up the entire roll and also provides totals for each part of the roll.
• The dice results are color coded for easier reading.
• Dice results are sorted.

Buttons - Variables - Sets - Tables:

• Includes a full set of the traditional gaming dice: d4, d6, d8, d10, d12, d20, d100.
• The Dice Roller window has rows of "Dice Buttons" that you can configure to hold a dice roll. More rows of dice buttons can be visible. Choose "Number of Dice Rows" in the "Dice" menu to adjust the number of visible rows. To edit a Dice Button control click (or right click [mac]) the button.
• You can track variables that retain their value for the entire roll but then recalculate for the next roll. Buttons can reference variables so that when modifiers and base attack bonuses change, you don't have to change all the buttons.
• As a GM you can force others to make rolls and have the results sent back to just yourself or to the whole group.
• Rolls can link to other button and/or variable rolls so as to chain them together.
• Using conditional statements and roll linking, the dice become an exceptionally powerful way for you to give output specific to the results of what you are rolling.
• Dice Sets can be created and saved so that you can switch between dice sets representing different characters, forms, or anything else that you need a saved list of dice rolls for.
• Rolls can be told to roll on a specific dice set, even if it is not the currently active dice set, which reduces the need to switch your active dice set during play. Also useful for requesting a die roll from more than one character / entity / list at a time.
• Tables can randomly return a result allowing all sorts of randomly generated results: names, treasure, encounters, cities, etc.
• A Roll can lookup a value from a table using a 'key' to return a specific value.
• The best way to use it is to play around with it!

Dice Buttons

Buttons appear on the main dice rolling window. You can setup your common rolls as a button and click the button to have it make the roll. Any roll can be placed inside a button. A button has a name and a roll value. The name is optional, but is useful for seeing what the button's roll does and for linking between buttons.

• To Edit a Button: Click a blank button, or Control Click (Right Click [mac]) a non-blank Button.
• Drag Reorder Buttons: Hold Alt/Option Key when dragging buttons.
• Add More Dice Buttons: You can add more dice buttons by looking under the "Dice" menu: Number of Dice Rows.
• Resize Buttons: You can change the size (wider or narrower) of dice buttons by visiting the Preferences: Dice Rolling: Approx. Dice Button Size. Dice button widths are calculated so this number is not absolute.
• To Delete a Button: Edit a button (see above) and erase its Name and Roll fields, it will then become a blank button again.

Rolling Dice:

Rolling dice is simple. Just type in the die rolls using "D" or "d" for the dice.

• 3d6 (This will roll 1d6 3 times and add them together)
• 12d50+10 (This will roll d50 12 times and add 10 to the final result)
• 5d4-4 (This will roll d4 5 times and subtract 4 from the final result)
• d (This will default to rolling 1d20)
• 6 (A roll can be a single numeric value which can be useful for variables and buttons representing an ability score, modifier, etc)

Reroll Min/Max:

Rerolling on a maximum or minimum result is done using "N" and "M". This is a quick way to add another roll if the result is minimum or maximum. For more complicated rolls or to reroll minimum or maximum rolls, please see the ScriptsFAQ

• 3M6 (This will roll 1d6 3 times. If any of the d6s result in a 6 then it is rolled again. So if the first 3 rolls are 3, 6, and 6 then two more d6s are rolled. If they are 3 and 6 then yet another d6 is rolled and if that is a 1 then the 3, 6, 6, 3, 6, and 1 are added for a final result of 25)
• 3N6 (This will roll 1d6 3 times. If any of the d6s result in a 1 then it si rolled again. So if the first 3 rolls are 3, 1, and 1 then two more d6s are rolled. If they are 3 and 1 then yet another d6 is rolled and if that is a 6 then the 3, 1, 1, 3, 1, and 6 are added for a final result of 15)

Use Math

You can use Multiply, Divide, Addition and Subtraction. ( * / + - )

• 3*(100d6)+20 (Multiply 100d6 by 3 and add 20)
• 50d6/2 (Divide 50d6 by 2)
• 1d100+10d6-3d4*5d8/2d2 (3d4 times 5d8 divided by 2d2 subtracted from (1d100 plus 10d6))
• (3d6-5)*10 ((3d6 subtract 5) multiply by 10)

Rolling Sets:

Use Brackets to enclose sets. You must have an opening and closing bracket. The number outside the opening bracket tells CB how many sets to roll:

• 6[3d6] (This will roll 6 sets of 3d6)
• 12[d50+10] (This will roll 12 set of d50+10)
• 3[6[3d6]] (This will roll 3 sets of 6 sets of 3d6)

Dropping Rolls:

You can drop rolls from a single roll or from a set using the tilde character: ( ~ )

• 7d6~1 (Rolls 7d6 and drops the lowest d6)
• 7[3d6]~1 (Rolls 7 sets of 3d6 dropping the lowest 3d6)
• 7[4d6~1]~1 (Rolls 7 sets of 4d6 dropping the lowest d6 AND dropping the lowest set.)

Reroll Dice (Greater Than / Less Than)

You can force rolls to "reroll" until they obtain a desired result by using < and >. The dice roller will attempt a roll up to 1000 times. If it is unable to force the roll to be within the specified range, it will give up.

• 7d6>10 (Forces the dice roller to reroll if the result of 7d6 is less than or equal to 10)
• 3[3d6]>100 (Forces the dice roller to reroll if the result is less than or equal to 100)
• 4d8>10<20 (Forces the dice roller to reroll if the result is less than or equal to 10 or more than or equal to 20)
• 2d100>15<90~1 (Forces the roll result to drop the lowest d100 and then to be greater than 15 and less than 90)
• 1d20>16 (Cheater Dice? Forces the roll result to be greater than 16! But the dice results will always display that the roll was forced by using > and <)

Comment Your Dice Rolls

You can add comments into your dice rolls. Just place your comments in quotes and they will show up in the final result. eg. "My Comment"

• 7D6 "Fireball Damage"
• IF (1d20+6) "To Hit" >= 26 THEN (1d20+6) "Critical Threat!" END

Multiple Rolls

You can make more than one roll in the same statement. Separate the rolls with a semicolon ( ; ). Each roll is treated as a separate roll. The results are separated so as to clearly see which roll rolled which result.

• 1d20 ; 1d8+3 (This will show the result of rolling 1d20, show a separator, and then show the result of 1d8 + 3)
• "Ilsalore's Initiative" 1d20+1 ; "Komek's Initiative" 1d20+6 (this will roll both initiatives and put a separator between them)

Use Logic

You can use IF, THEN, ELSE, END to control rolling. You must use the following test operators:

• >> (greater than)
• << (less than)
• >= (greater than or equal to)
• <= (less than or equal to)
• == (equal to)
• <> or != (not equal to)

The LEFT test condition can be located inside the statement or directly to the left of the statement: If the left test condition is located inside the statement it is not added to the total result. Likewise, if the Left condition is located outside the statement it will be used in the total.

• 1d6 IF >> 3 THEN +1d6 END
  (if the 1d6 is greater than 3 then 1d6 will be added to the roll)
• IF 1d6 >> 3 THEN 1d6 ELSE 1d4 END
  (if 1d6 is greater than 3 then 1d6 WILL BE ROLLED else 1d4 will be rolled)

Conditions can be nested. The results and tests can be dice rolls.

• (1d20+6) IF >= 14 THEN +1d20+6 END
  (Roll a d20 + to hit bonus if its a threat of critical roll again!)
• IF 1d20+10 << 15 THEN "Bad Roll!" ELSE IF 3d6 == 18 THEN "Perfect Roll" 1d100 END END
  (Example of nested IF THEN ELSE END statements. Remember each IF must have an END!)

Play Sounds

You can have the Dice Roller play any sounds you have in the CrystalBallData/User_Data/Sounds/ folder. To play a sound use the Pound ( # ) symbol to specify the name of the file to play. You can use MP3 or WAV files.

• 3D6 #LightSaberSound.mp3#
• IF (1d20+6) #Swipe.mp3# >= 27 THEN (1d20+6) #Cheer.mp3# END
• #Thunder.mp3# (Yes you can even play a sound without specifying a roll! An icon will be added to the button to indicate that the button is a sound only.)

Button Linked Rolls

You can link a roll to an existing button's name. If you had a button named "Critical Damage" you could make a roll that linked to this button if you rolled a critical hit. To link to a button, place the button's name between underscores ( _ ).

• _Critlcal Damage_ (this will roll the Critical Damage button)
• IF 1d20 >= 19 THEN _Critical Damage_ ELSE _Normal Damage_ END
  (rolls d20. on a result of 19 or 20 it rolls the "Critical Damage" button, otherwise it rolls the "Normal Damage" button)

Variables

A Variable is similar to a Button in that it has a name and a roll / value. The main difference is that when a Variable is referenced during a roll, it doesn't change it's value until the roll is finished. So, if a variable's value is 1d6 and a roll references it three times, all three references will be the same value.

This is extremely useful for determining the results of a roll where the effects are dependent on more than a single "IF THEN ELSE END" statement. Variables are also an excellent location to store non-rolled values like Ability Modifiers and other static values that are useful to other rolls.

To link to a variable in a roll, enclose the variable's name in dollar signs ( $ ).

Click the "Edit Variables" button on the Dice Roller window to edit the current Dice Set's Variables.

• $Strength Modifier$ (this will roll the variable named "Strength Modifier")
• d20 + $Dexterity Modifier$ (this will roll d20 and add whatever roll is stored in the 'Dexterity Modifier' variable)
• $normal damage$ + $normal damage$ (this would roll normal damage once and add the same value to itself since the value doesn't change until the roll is done)
• IF $rps$ == 1 THEN "Rock" ELSE IF $rps$ == 2 THEN "Paper" ELSE "Scissors" END END
  (rolls "rock, paper, scissors". The variable "rps" has a roll of 1d3.)

GM Forced Rolls

A player flagged as GM can force other players to make a roll and have the results of the roll seen by everyone or just show it to the GM.

The syntax has three parts (comma separated) and surrounded in question marks.

• ?*Roll , *Send (single/all) , *Return (public/private)?

*Roll

The roll that the other player(s) should make. This could be any valid roll and can include text, button name links, variables, sounds, pretty much anything that a roll can do. All links and sounds will be relevant to the machine making the roll, and not the GM's machine. If a player is missing a variable name that is requested, the player will be prompted to enter a value for that variable.

*Send (single/all)

• Valid values are : true, false, yes, no, t, f, y, n. Defaults to true.
• true / yes : sends the request to all players
• false / no : sends the request just to the players selected in the chat window's participant list.

*Return (public/private)

• Tells if the roll's result should be shown to everyone, or just the requesting GM. Valid values are: true, false, yes, no, t, f, y, n. Defaults to false.
• true / yes : everyone will see the roll
• false / no : just the requesting GM will see the roll

The last two parts (Send & Return) are optional, so a forced roll could be made like: ?1d20?
This roll would make all the other users roll 1d20 and return the result back just so the requesting GM can see it (they'll never know they rolled it).

Forced Rolls become exceptionally powerful for surprise checks and similar spot, listen, "you didn't see it coming" types of checks. Note: If a variable is requested to be rolled, and the player doesn't have that variable, a dialog will open on the player's machine asking for the value of the variable that will then be added as a variable for the player and the value returned to the roll requester.

• ?$spot$? (Requests that the variable "spot" be rolled on all machines and be returned back privately. If someone doesn't have a spot variable, they'll be requested to enter it. The sending public/private and receiving public/private parts will be default values since they weren't given a value.)
• ?$Initiative$,True,True? (Requests an $Inititative$ variable from ALL users and returns the roll for EVERYONE to see.)
• ?$Spot$,True,False? (Requests a $Spot$ variable from ALL users and returns the result only to the requesting GM.)
• ?1d20,False,True? (Requests a roll (1d20) from the SELECTED users in the chat window, and returns the result for EVERYONE to see.)
• ?5d6+5 "Fireball Damage",False,False? (Requests a roll from the SELECTED users in the chat window, and returns the result for only the requesting GM to see.)

Roll Across Sets

You can make a roll on a non-active dice set without having to change to that dice set. This can be helpful if tracking more than one character at a time by using different sets. Use an At symbols ( @ ) around the dice set name to make the roll on.

If a variable or button is told to roll in a specific dice set, any variables or buttons referenced from that button or variable will also roll in that same dice set unless it specifically says not to later in the chain. This way, a roll will stay in the specified dice set to resolve all linked rolls.

• $Initiative$ @Wyvern@ (this will look for and roll the 'Initiative' variable from the Wyvern dice set)
• $Spot$ @Wyvern@ ; $Spot$ (this will look for and roll the 'Spot' variable from the Wyvern dice set and then roll the 'Spot' variable in the current dice set)
• _Strength Check_ @Ilsalore@ + _Strength Check_ @Komek@ (rolls a 'Strength Check' button in Ilsalore's dice set and adds that value to a 'Strength Check' made in Komek's dice set. If one of the buttons is missing, no value is given.)

Complex Rolls (Please Note)

If your rolls are very complex and require too much time to render in colors it will be shown in plain text to speed things up. Also if your rolls are very long and large it may take a while for the results field to update. The roll will be done in less than a second, it just takes a while for the field to update. (For large rolls)

Table - Random Rolling

There are two types of ways to get information from a table. The first is randomly returning a result and the second is to detail which data to get. Random rolling on a table allows for random generation of names, treasure, encounters, hit locations, and any other random selection from a list of items. The dice roller looks in the "TableData" folders for a requested table to roll on. Use the "pipe" character ( | ) to enclose a table-roll.

• |"Treasure"| (This will randomly select a row from the "Treasure" table and return the found value)
• |"Treasure.xml", "Minor"| (This will randomly select a row from the "Treasure" table's subtable named "Minor". If no subtable is given, then the first subtable of the table is used.

To create a new table for table-rolling use the menu: Customize > Table Editor > New Table.

There are two columns names used in table-rolling: "Weight" and "Value". Any extra columns are ignored.

The "Weight" column can be used for giving each row a certain chance to be rolled. If an item is the result of a roll between 76 -> 82, then its weight is 7, since 7 chances would result in the item. The total weights are added and the random item is picked using these weights. The total of the weights need not equal 100. The "Weight" column is optional if you wish each row to have the same chance to be rolled.

For example, a Hit Location table has 5 rows in a Value column: head, arm, leg, torso, and back. This same table also has a Weight column with rows with the values of 1, 7, 5, 3, and 2. So the weights of the values are head = 1, arm = 7, leg = 5, torso = 3, and back = 2. The total of the weights is 1 + 7 + 5 + 3 + 2 = 18. So, head has a 1 in 18 chance of being rolled. Arm = 7/18, leg = 5/18, torso = 3/18, and back = 2/18.

Weight	Value
1	head
7	arm
5	leg
3	torso
2	back

If no column has the name "Value" then the first non-Weight column is automatically chosen as the Value column. The "Value" is what is returned by the roll.

The cell's value is considered a string. But, if the cell's value starts with "Roll=" then the cell is treated as a dice-roll. A new dice-roll is made using the text following "Roll=" as the dice-roll's text.

• roll = 2[|"Treasure","Wondrous"|] (This entry could be put in the cell of a Treasure table. This would roll 2 times (note the use of 2[ ] for rolling a set) on the Treasure table's Wondrous subtable)
• http://crystalballsoft.com/apps/cblite/examples/ has an example table entitled "DungeonCrawl.xml" which is a table set up for table rolling. For a discussion on this example table please see the related Message Board thread Rolling On Tables

Instead of providing a return number value, a table cell can also be defined as a roll. Normally, the value of a cell is returned as is. Instead if the cell's value starts with [b]roll=[/b] then the value of the cell is rolled and the result returned. This is a great way to have a cell link to other tables or for a treasure generator to reroll on a table.

For example, a table's value column has a value of roll=1d20. This will roll 1d20 and return the result instead of returning the string "roll=1d20".
If roll=|"tablename", "subtablename"| is the result of a table roll, then it will preform another table roll and return that as the result. This allows linking cells of tables to other rolls.

Table - Lookups

Tables can also be used to lookup values. There are 2 special column names that can be used for table look up: key and value.
The "key" column of the table contains the "keys". These are matchable values that define a row and should be unique. If there is more than one matching value than it is undefined which will be used on a lookup.
The "value" column is the column of the value to return if the column name isn't given.
So, given a specific key, the lookup returns the associated value. This allows stats, data, character information and other data to be stored in a table and accessed by a roll. Use the "pipe" character ( | ) to enclose a table-lookup.
There are four parameters for looking up a table value. The first is the table name which is the table's name to be getting values from. The second parameter is the subtable name of the table. The third is the "key" to lookup the value from the subtable's "key" column. The fourth column is optional. If not used, then the "value" column is used for returning the value. If used, it defines which column to return the value from. This can be used if a row is a character or monster and the lookup is to return a value from that character's/monster's row.

• |"character - Dritz", "level - 1", "BAB"| (This loads the "Character - Dritz" table, then gets the "level - 1" subtable, and finds the row whose first column is "BAB" and returns the value in that row's second column)
• |"Module Characters", "NPCs", "Big Bob", "Int"| (This loads the "Module Characters" table, then gets the "NPCs" subtable, and finds the row whose first column is "Big Bob". It then returns the "Int" column's value.)
• |"treasure", "minor", "Global of Invulnerability"| (This gets the Treasure.xml table and pulls its Minor subtable. It then searches for "Globe of Invulnerability" from the items in the first column and returns the cell that matches the found row from the second column)

Setting a Variable in a Roll

The results of a roll can be placed in a variable for later access. The variable gets the result of the roll. The next time the variable is called, the new value is returned.

• $var$ = 1d20 (1d20 is rolled. The result of the roll is put in the variable "var". If var already exists, its value is overwritten. If var doesn't exist then it is added. Only the result of the roll is put in the variable, so later requests for the variable return the result of the original 1d20 instead of rolling 1d20 again)
• $sounds$ = #MySound.wav# "MySound has been played." (If a sound(s) and/or a string(s) are put in the roll, the variable will have the roll and sound stored with it. If the variable is used later, the same sound(s) and text are also included)
• Setting a variable to the value of a roll can use dual operators to make setting easier. These include:
  • $var$ += 10 is the same as $var$ = $var$ + 10
  • $var$ -= 10 is the same as $var$ = $var$ - 10
  • $var$ *= 10 is the same as $var$ = $var$ * 10
  • $var$ /= 10 is the same as $var$ = $var$ / 10
  • $var$ ^= 10 is the same as $var$ = $var$ ^ 10
  • $var$ %= 10 is the same as $var$ = $var$ % 10

Roll Directives

Directives allow the functionality of rolling to change. They are an inline way to handle dice preferences. Directives can be applied to separate parts of a roll. Nesting directives is a powerful way to customize the results of a roll.

The defaults for the directives can be modified in the "DefaultDiceDirectives.xml" table. Just open the table in the table editor window (accessible by clicking on the "DefaultDiceDirectives.xml" file in the Menu: Customize > Table Editor > User_Data > Table_File). Find the directive whose value needs changed, and change to the new default value.

Directives are not case sensitive. SORT is the same as sort which is the same as SoRt.

Directives apply to the whole roll, and not to any single part when used inline with dice rolls.

The following is a list of directives and their function:

• Sort : Sort is used to change how the results of rolling more than one dice is displayed
  Usage:
  • :sort=d: Sorts results in (D)escending order
  • :sort=a: Sorts results in (A)scending order
  • :sort=n: Does not sort results. Results appear as they occur naturally
  Examples:
  • :sort=d:3d10 Result: 3d10(10, 5, 3)=18 (Shows the results in descending order which is the default)
  • :sort=a:3d10 Result: 3d10(3, 5, 10)=18 (Shows the results in ascending order)
  • :sort=n:3d10 Result: 3d10(5, 10, 3)=18 (Shows the results in no order)
• DoNotSend : This prevents a roll from being sent to other networked players no matter your current Sending setting. For common rolls that are for your eyes only, this is an easy way to keep them from being to shown to everyone.
  Usage:
  • :DoNotSend: If this is found in a roll, the roll will not be sent to other players
  Examples:
  • :DoNotSend: 1d20 + 10 "NPC pickpocket check" The 1d20 + 10 rolls and shows its result to you and is not sent to other players even if sending rolls is set to public or private

Dice Functions

Dice Functions are operations that can be performed on a part of a dice roll that will effect the display and/or result of the Roll contained in the function.

Dice Functions are useful because they can be applied to any part of the dice roll, similar to Dice Sets. Dice Functions are called by name, while the dice roll the function is going to operate on is enclosed in parenthesis. Such as Round(1d6 * 0.33). Dice Fuctions can also be nested.

The following is a list of Dice Functions and what they do.

• Ceil ([Short for "Ceiling"] Shows the result of the roll rounded UP to the next nearest whole number.)
  • Ceil(15 * 0.33) Result = 5
  • Ceil(138 / 13) Result = 11
  • Ceil(53 / 10) Result = 6
• Floor (Shows the result of the roll rounded DOWN to the next nearest whole number.)
  • Floor(15 * 0.33) Result = 4
  • Floor(138 / 13) Result = 10
  • Floor(53 / 10) Result = 5
• Hide (Nothing is displayed. The Roll contained inside the function is NOT SHOWN AT ALL)
  • Hide(8d6+8 "Something") Nothing is displayed in the results.
  • Hide($myvar$ = 1d6+30) Nothing is displayed in the results. However, $myvar$ is assigned the result of "1d6+30"
• NumbersOnly (Removes all "text" and sound from the roll so that no sounds will play for that part of the roll if a sound is specified and no text is show in the result.)
  • NumbersOnly(2d10-3 "my text" #mysound.mp3#) No sound played. No comments are displayed in result.
• ResultOnly (Shows only the result of the roll, including any "text" elements. All calculations for the roll are hidden.)
  • ResultOnly(1d6+10) 16=16
  • ResultOnly(10d10+15 "Some Text") 59=59 Some Text
• Round (Shows the result of the roll rounded to the next nearest whole number.)
  • Round(15 * 0.33) Result = 5
  • Round(138 / 13) Result = 11
  • Round(53 / 10) Result = 5
• Script Runs a script by the name supplied. It first sees if a script with this name exists in the current dice set and if not found there it checks for a script with the name in the Scripts folder. See the ScriptsFAQ for more information about scripting. Parameters can be passed to the called script. The parameters appear after the script name in a comma separated list. The parameters are given the name "paramX" where X is the 1 based number of the parameter so that the first parameter has the name param1 and the second has the name param2. The name is used to access the parameter value from within the called script. Parameters can also be named by using the following syntax "myvalue=Brett". A variable with the name "myvalue" would be assigned the value "Brett". If named, the parameter will get set with the given name and with the "paramX" name. Use the GetScriptParameter method to get the variable's value in the called script. Parameters and scriptname work just like the Script function CallScript. See the CallScript function for examples and further explanations.
  • Script("ScriptName", "A String") Runs the script called "ScriptName" passing the paramter "A String" to the script. See CallScript for more information about script parameters.
• StripComments (Removes all "comment" elements from the roll.)
  • StripComments(1d20+7 "Attack") 1[1d20(5)+7=12]=12
• StripSounds (Removes all sound from the roll so that no sounds will play for that part of the roll if a sound is specified.)
  • StripSounds(1d20+7 #mysound.mp3#) No sound played.