The RollPlay Dice library is a multi-platform C
application programming interface (API) which performs dice rolling
services. RollPlay provides:
- Parsing of complex role-playing style dice descriptions
- Open-ended rolls
- Collective dice tests, for games like Shadowrun, Earthdawn, the Storyteller system, et. al.
- Multiple algorithms for random number generation
- Roll statistic tracking
- Rolls against set target numbers
Parsing
RollPlay’s main purpose is to provide a standard, cross-platform tool to turn regular dice descriptions like “3d6 + 12d4 - 15d10 + 3” into computer usable dice objects. RollPlay easily handles odd dice requests like “15397d42” as it can take dice and side values from 0 to 65,535. Constants (like the “+3” in the first sentence of this paragraph) can be any reasonable positive or negative value.
The dice string is a list of dice forms separated by plus or minus signs. Your dice strings can contain as many different dice forms as you have memory for. And since each form only takes a few bytes, that should be more than you will ever need. Naturally, you can also have as many different simultaneous dice strings as will fit in RAM.
RollPlay’s concept of dice syntax allows for each form to contain a multiplier, if desired. Such forms begin with the multiplier followed by an ‘x’ and then a normal form. So if you wanted to take the result of a 3d6 roll and multiply it by 4, the form would be “4x3d6”. Multupliers can be any reasonable value.
Of course, the API also supports creation of simple forms without using strings, since sometimes you have real numbers and don’t want to convert to ASCII.
Open rolls
Many games use the concept of an open roll. This is a roll that has no upper limit. They work by rolling a die, and if the maximum value for the die comes up, you add that value to another roll of the same die. If the second roll comes up at the maximum, you add and roll again, and so on.
RollPlay handles these kinds of rolls as well. Such rolls are indicated with a ‘t’ in the form instead of a ‘d’. For example, to indicate an open six-sided roll, the form would be ‘t6’. The rest of the syntax works just the same, so ‘3t6’ means to roll three open-ended six-sided dice and add them together. You can mix tests with normal rolls as well.
An alternate open-ended roll is provided as well, which fits a number of house rules. It is the same as the open test, but instead of adding the maximum value of the dice, you add that value minus one. For example, if you rolled a 6 one of these modified open tests, you roll again and add five instead of six. This form uses an ‘s’ in place of the ‘d’.
Collective tests
Games like Shadowrun, Earthdawn and others use collective tests. These are rolls where a number of dice are rolled (in many cases, open-endedly), but each dice is considered seperately instead of summing all the dice. Though the RollPlay parser does not allow a way to specify tests like this, RollPlay provides a number of API calls specifically designed to make these kinds of tests. You perform collective tests with dice objects, so each “die” of the collective test can be a full-blown dice string like “7d8 + 2t6”.
Randomness options
RollPlay provides a number of different methods of random number generation. Many of these methods provide much better random number generation than the random number generators built into most compilers and APIs. Some are also faster.
Statistics
At your option, you can create any dice object so that it will keep a history of its rolls. This history takes the form of an array that holds of count of how many times the dice object has returned each possible value. For dice with many sides, this can take a largish amount of memory. APIs are provided to get and set this history however you like, allowing the possibility of saving histories.
Target tests
APIs exist for determining if a roll exceeded a given target. This is a bit more useful for collected tests, as RollPlay will count successes for you.
Limits
RollPlay parsing syntax does not allow parentheses. This means that it will not distribute for you. You cannot specify “3x(2d6-1)”. This should not really be a large problem, as multiplication obeys the distributive property. Thus, you could specify “3x2d6 - 3” for the same effect.
You also cannot specify a dice form in place of a numeral. For example, you cannot make the number of sides for a form be another dice form, like this “2d(4d8)”. If you really need to do this, you will have to do it yourself using multiple API calls.
Licence
RollPlay is distributed under the GNU Lesser General Public License (LGPL).
Downloading
Under the terms of the LGPL, source code for RollPlay is publicly available, hosted by SourceForge:
](http://sourceforge.net)
The latest versions of the library and the code can be downloaded from SourceForge here or from some alternate sources. The full list of download sites is:
Version History
1.2 - May 29, 2001
- First SourceForge release.
- Added support for keeping minimum and maximum die/dice.
- Added CompareDiceObjects function to API.
- Added IsValidDiceString function to API.
- Added TargetedRoll function to API.
- Added TargetedTest function to API.
- Obsoleted TargetRoll function.
- Obsoleted TargetTest function.
1.1 - August 25, 1997
- Initial Windows release.
- McLaughlin’s ULTRALibU randomness option added for Macintosh
- Modified LFSR code now is properly random. Embarrasing fix to algorithm.
- Fixed seed restting to the same value when you called SetRandomMethod with kRandom_ModifiedLSFR multiple times in row.
1.0 - November 15, 1996
- Initial release (Mac only)
Credits
Most random number generators were inspired by Bruce Schneier’s Applied Cryptography, and implemented by Wordman. The Ultra psuedo-random number generator was implemented with code from the Internet, created by Prof. George Marsaglia and co-workers, Dept. of Statistics, Florida State University, with Mac coding by Dr. Michael P. McLaughlin.