class DieRoll

A DieRoll is a fixed collection of dice, such as 3d6 or 1d20. More...

Full namefun::DieRoll
Definition#include <fun/DieRoll.h>
Inheritsfun::Serializable [public ]
List of all Methods
Annotated List

Public Types

Public Methods

Public Static Methods

Detailed Description

A DieRoll is a fixed collection of dice, such as 3d6 or 1d20. Its most useful method is roll(), although it does have methods such as min(), max(), isFlat(), and distribution() for examining its expected results.

DieRoll instances are not constructed directly; use DieRoll::fromString().

 DieRoll ()


Creates a new (useless) DieRoll.

 DieRoll (const DieRoll &other)


Creates a new copy of the given DieRoll. DieRolls use reference counting, so this is fast.

 ~DieRoll ()



DieRoll & operator= (const DieRoll &other)


Copies the given DieRoll. DieRolls use reference counting, so this is fast.

void  serialize (Serializer &ser)


[const virtual]

Saves the DieRoll to the given Serializer.

Reimplemented from Serializable.

void  deserialize (const Deserializer &ser)



Loads the DieRoll from the given Deserializer.

Reimplemented from Serializable.

int  roll ()


[const virtual]

Rolls the dice and returns the result. This is what a DieRoll object lives for!

int  min ()


[const virtual]

Returns the minimum possible result.

int  max ()


[const virtual]

Returns the maximum possible result.

bool  isFlat ()


[const virtual]

Returns true if the distribution of the DieRoll's results will be flat rather than a bell curve. Note that this may be misleading for compound results involving multiplication, such as d6*2. (This will likely return true in that case, even though your chance of rolling a 2 is considerably higher than your chance of rolling a 3, ha ha.)

WeightedValue (struct)


A list of WeightedValues is returned by distribution().

QValueList  distribution ()



Returns a list of WeightedValues giving the DieRoll's expected distribution, or an empty list for DieRolls which do not support it. Each element in the list corresponds to a possible result. For example, a d2 should generate a 1 50% of the time and a 2 50% of the time, so it would return a list of two elements: { 1, 0.5 } and { 2, 0.5 }. distribution() for 2d2 would return a list with three elements: { 2, 0.25 }, { 3, 0.5 }, and { 4, 0.25 }.

QString  toString ()


[const virtual]

Returns the DieRoll in a format which should be readable by DieRoll::fromString() (as well as by people). The result is most likely cached by the DieRoll, not recalculated every time this is called, so it should be fast.

DieRoll  fromString (const QString &src)



This creates DieRoll instances from strings such as "d6", "3d6", "3d6+3" and "3d6*3", and "d8+d12".

void  addDieRollParser (PluginDieRollParser dp)



Games which have their own concept of dice & rolled results can plug in DieRollParsers. A PluginDieRollParser takes a QString, parses the entire thing if it can, and returns a SolidPlastic object. If it can't parse the entire string, it returns NULL; if the string contains any operators (+, -, *), the parser will be called again with the substrings.

Some examples:

Dream Pod 9's Silhouette system uses "1d6", "2d6", etc., but the result is the highest single die roll, not the sum of the rolled dice. There are two special cases: each additional 6 after the first adds 1 to the total; and if all rolled dice come up 1, the result is 0 (a fumble), and any modifiers are not applied. (Unfortunately, to keep from confusing "normal" 3d6 from Silhouette's 3d6, you might want your parser to look for "3s6", "s3d6", "3s", or "s3" or something. Also, because modifiers aren't supposed to be applied when a fumble is rolled, you might want your parser to handle modifiers.)

DemonBlade/xB9/Dark Tortoise's WarEngine uses "1k1", "2k1", etc., where the number before the "k" is the number of 6-sided dice rolled, and the number after the "k" is the number of dice "kept". So "3k2" means roll 3d6 and return the sum of the highest two.

void  removeDieRollParser (PluginDieRollParser dp)



Removes the given PluginDieRollParser from the list of plugged-in parsers.

void  testRolls (const DieRoll &d, int rolls, bool showSubs)



This tests two things, and prints its results on cout. First, it tests the distribution of the generated numbers; if we're rolling d6's, what percentage of the results will be 1's, 2's, 3's, etc. Second (optionally), for each result, what is the chance that the next result will be the same? (Hopefully the chance of rolling two 1's in a row will be the same as the chance of rolling a 1 followed by a 2).

dthe die roll to perform
rollsthe number of times to roll the dice
showSubstrue if subsequent results will be shown (that is, when a number is rolled, whether to keep track of what the next number rolled is)

Generated by: stephan on cheyenne on Mon Aug 11 14:06:52 2003, using kdoc 2.0a54.