Game.TCOD.Mersenne

This toolkit is an implementation of two fast and high quality pseudorandom number generators: * a Mersenne twister generator, * a Complementary-Multiply-With-Carry generator. CMWC is faster than MT (see table below) and has a much better period (1039460 vs. 106001). It is the default algo since libtcod 1.5.0.

Documentation

randomGetInstance :: IO TCODRandom

Default generator

The simplest way to get random number is to use the default generator. The first time you get this generator, it is initialized by calling TCOD_random_new. Then, on successive calls, this function returns the same generator (singleton pattern).

randomNew :: RandomAlgorithm -> IO TCODRandom

Generators with random seeds

You can also create as many generators as you want with a random seed (the number of seconds since Jan 1 1970 at the time the constructor is called). Warning ! If you call this function several times in the same second, it will return the same generator.

randomSave :: TCODRandom -> IO TCODRandom

Saving a RNG state into generator-backup

randomRestore

Arguments

:: TCODRandom

generator that will be restored from backup

-> TCODRandom

backup-generator, returned by randomSave

-> IO ()

Restoring a saved state

And restore it later. This makes it possible to get the same series of number several times with a single generator.

randomNewFromSeed :: RandomAlgorithm -> Word -> IO TCODRandom

Generators with user defined seeds

Finally, you can create generators with a specific seed. Those allow you to get a reproducible set of random numbers. You can for example save a dungeon in a file by saving only the seed used for its generation (provided you have a determinist generation algorithm)

randomDelete :: TCODRandom -> IO ()

Destroying a RNG

To release resources used by a generator, use the function. NB : do not delete the default random generator !

randomSetDistribution :: TCODRandom -> Distribution -> IO ()

Setting the default RNG distribution

Note: See docs for Distribution

randomGetInt

Arguments

:: TCODRandom

-> Int

min. Range of values returned. Each time you call this function, you get a number between (including) min and max

-> Int

max

-> IO Int

Getting an integer

Once you obtained a generator (using one of those methods), you can get random numbers using the following functions, using either the explicit or simplified API where applicable:

randomGetDouble

Arguments

:: TCODRandom

-> Double

min. Range of values returned. Each time you call this function, you get a number between (including) min and max

-> Double

max

-> IO Double

Getting a floating point number

Once you obtained a generator (using one of those methods), you can get random numbers using the following functions, using either the explicit or simplified API where applicable:

randomGetIntMean

Arguments

:: TCODRandom

-> Int

min. Range of values returned. Each time you call this function, you get a number between (including) min and max

-> Int

max

-> Int

mean. This is used to set a custom mean, ie, not min+((max-min)/2). It can even be outside of the min-max range. Using a mean will force the use of a weighted (Gaussian) distribution, even if linear is set.

-> IO Int

Getting an integer

Once you obtained a generator (using one of those methods), you can get random numbers using the following functions, using either the explicit or simplified API where applicable:

randomGetDoubleMean

Arguments

:: TCODRandom

-> Double

min. Range of values returned. Each time you call this function, you get a number between (including) min and max

-> Double

max

-> Double

mean. This is used to set a custom mean, ie, not min+((max-min)/2). It can even be outside of the min-max range. Using a mean will force the use of a weighted (Gaussian) distribution, even if linear is set.

-> IO Double

Getting a floating point number

Once you obtained a generator (using one of those methods), you can get random numbers using the following functions, using either the explicit or simplified API where applicable:

randomDiceNew :: String -> IO Dice

Create dnd-like dice from description string like "3d6+2"

randomDiceRoll :: TCODRandom -> Dice -> IO Int

Roll dice and return resulted dice side

randomDiceRollS :: TCODRandom -> String -> IO Int

Roll dice without initiating, see randomDiceNew