Class TCODRandom¶

Defined in File mersenne.hpp

Class Documentation¶

class TCODRandom¶

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.

Relative performances in two independent tests (lower is better) :

Algorithm	Numbers generated	Perf (1)	Perf (2)
MT	integer	62	50
MT	float	54	45
CMWC	integer	21	34
CMWC	float	32	27

For Python users:

Python already has great builtin random generators. But some parts of the Doryen library (noise, heightmap, …) uses RNG as parameters. If you intend to use those functions, you must provide a RNG created with the library.

For C# users:

.NET already has great builtin random generators. But some parts of the Doryen library (noise, heightmap, …) uses RNG as parameters. If you intend to use those functions, you must provide a RNG created with the library.

Public Functions

TCODRandom(TCOD_random_algo_t algo = TCOD_RNG_CMWC, bool allocate = true)¶

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.

TCODRandom::TCODRandom() // Defaults to ComplementaryMultiplyWithCarry TCODRandom::TCODRandom(TCODRandomType algo)

Parameters: algo – The PRNG algorithm the generator should be using.

TCODRandom(uint32_t seed, TCOD_random_algo_t algo = TCOD_RNG_CMWC)¶

@noop random_init
@noop Generators with user defined seeds
@brief 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)
@noop TCODRandom::TCODRandom (uint32_t seed, TCOD_random_algo_t algo = TCOD_RNG_CMWC);
@noop TCOD_random_t TCOD_random_new_from_seed (TCOD_random_algo_t algo, uint32_t seed);
@noop random_new_from_seed(seed, algo=RNG_CMWC)
@noop#
  TCODRandom::TCODRandom(uint32_t seed) // Defaults to ComplementaryMultiplyWithCarry
  TCODRandom::TCODRandom(uint32_t seed, TCODRandomType algo)
@param seed The 32 bits seed used to initialize the generator. Two generators created with the same seed will generate the same set of pseudorandom numbers.
@param algo The PRNG algorithm the generator should be using.
@noop

default generator TCODRandom * default = TCODRandom::getInstance(); another random generator TCODRandom * myRandom = new TCODRandom(); a random generator with a specific seed TCODRandom * myDeterministRandom = new TCODRandom(0xdeadbeef);

default generator TCOD_random_t default = TCOD_random_get_instance(); another random generator TCOD_random_t my_random = TCOD_random_new(TCOD_RNG_CMWC); a random generator with a specific seed TCOD_random_t my_determinist_random = TCOD_random_new_from_seed(TCOD_RNG_CMWC,0xdeadbeef);

default generator

default = libtcod.random_get_instance() another random generator

my_random = libtcod.random_new() a random generator with a specific seed

my_determinist_random = libtcod.random_new_from_seed(0xdeadbeef)

inline explicit TCODRandom(TCOD_Random *mersenne)¶

Take ownership of a TCOD_Random* pointer.

New in version 1.16.

TCODRandom(const TCODRandom&) = delete¶

TCODRandom &operator=(const TCODRandom&) = delete¶

inline TCODRandom(TCODRandom &&rhs)¶

inline TCODRandom &operator=(TCODRandom &&rhs) noexcept¶

virtual ~TCODRandom()¶

@noop random_init
@noop Destroying a RNG
@brief To release resources used by a generator, use those functions :
  NB : do not delete the default random generator !
@noop TCODRandom::~TCODRandom()
@noop void TCOD_random_delete(TCOD_random_t mersenne)
@noop random_delete(mersenne)
@noop# void TCODRandom::Dispose()
@param mersenne In the C and Python versions, the generator handler, returned by the initialization functions.
@noop

create a generator TCODRandom *rnd = new TCODRandom(); use it … destroy it delete rnd;

create a generator TCOD_random_t rnd = TCOD_random_new(); use it … destroy it TCOD_random_delete(rnd);

create a generator

rnd = libtcod.random_new() use it

… destroy it

libtcod.random_delete(rnd)

inline void setDistribution(TCOD_distribution_t distribution)¶

@noop random_distro
@noop random
@noop Using a generator
@noop Setting the default RNG distribution
@brief Random numbers can be obtained using several different distributions. Linear is default, but if you wish to use one of the available Gaussian distributions, you can use this function to tell libtcod which is your preferred distribution. All random number getters will then use that distribution automatically to fetch your random numbers.

The distributions available are as follows:

TCOD_DISTRIBUTION_LINEAR This is the default distribution. It will return a number from a range min-max. The numbers will be evenly distributed, ie, each number from the range has the exact same chance of being selected.
TCOD_DISTRIBUTION_GAUSSIAN This distribution does not have minimum and maximum values. Instead, a mean and a standard deviation are used. The mean is the central value. It will appear with the greatest frequency. The farther away from the mean, the less the probability of appearing the possible results have. Although extreme values are possible, 99.7% of the results will be within the radius of 3 standard deviations from the mean. So, if the mean is 0 and the standard deviation is 5, the numbers will mostly fall in the (-15,15) range.
TCOD_DISTRIBUTION_GAUSSIAN_RANGE This one takes minimum and maximum values. Under the hood, it computes the mean (which falls right between the minimum and maximum) and the standard deviation and applies a standard Gaussian distribution to the values. The difference is that the result is always guaranteed to be in the min-max range.
TCOD_DISTRIBUTION_GAUSSIAN_INVERSE Essentially, this is the same as TCOD_DISTRIBUTION_GAUSSIAN. The difference is that the values near +3 and -3 standard deviations from the mean have the highest possibility of appearing, while the mean has the lowest.
TCOD_DISTRIBUTION_GAUSSIAN_RANGE_INVERSE Essentially, this is the same as TCOD_DISTRIBUTION_GAUSSIAN_RANGE, but the min and max values have the greatest probability of appearing, while the values between them, the lowest.

There exist functions to also specify both a min-max range AND a custom mean, which can be any value (possibly either min or max, but it can even be outside that range). In case such a function is used, the distributions will trigger a slightly different behaviour: TCOD_DISTRIBUTION_LINEAR TCOD_DISTRIBUTION_GAUSSIAN TCOD_DISTRIBUTION_GAUSSIAN_RANGE In these cases, the selected mean will have the highest probability of appearing.

TCOD_DISTRIBUTION_GAUSSIAN_INVERSE TCOD_DISTRIBUTION_GAUSSIAN_RANGE_INVERSE In these cases, the selected mean will appear with the lowest frequency.

Parameters

mersenne – In the C and Python versions, the generator handler, returned by the initialization functions. If NULL, the default generator is used..
distribution – The distribution constant from the available set:
- TCOD_DISTRIBUTION_LINEAR
- TCOD_DISTRIBUTION_GAUSSIAN
- TCOD_DISTRIBUTION_GAUSSIAN_RANGE
- TCOD_DISTRIBUTION_GAUSSIAN_INVERSE
- TCOD_DISTRIBUTION_GAUSSIAN_RANGE_INVERSE

inline int getInt(int min, int max, int mean = 0)¶

@noop random_use
@noop random
@noop Using a generator
@noop Getting an integer
@brief 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:
@noop

explicit API: int TCODRandom::getInt(int min, int max, int mean = 0)

simplified API: int TCODRandom::get(int min, int max, int mean = 0)

int TCOD_random_get_int(TCOD_random_t mersenne, int min, int max) int TCOD_random_get_int_mean(TCOD_random_t mersenne, int min, int max, int mean)

Parameters

mersenne – In the C and Python versions, the generator handler, returned by the initialization functions. If NULL, the default generator is used..
min, max – Range of values returned. Each time you call this function, you get a number between (including) min and max
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.

inline int get(int min, int max, int mean = 0)¶

inline float getFloat(float min, float max, float mean = 0.0f)¶

@noop random_use
@noop Getting a float
@brief To get a random floating point number, using either the explicit or simplified API where applicable
@noop

explicit API: float TCODRandom::getFloat(float min, float max, float mean = 0.0f)

simplified API: float TCODRandom::get(float min, float max, float mean = 0.0f)

float TCOD_random_get_float(TCOD_random_t mersenne, float min, float max) float TCOD_random_get_float_mean(TCOD_random_t mersenne, float min, float max, float mean)

default generator TCODRandom * default = TCODRandom::getInstance(); int aRandomIntBetween0And1000 = default->getInt(0,1000); int anotherRandomInt = default->get(0,1000); another random generator TCODRandom *myRandom = new TCODRandom(); float aRandomFloatBetween0And1000 = myRandom->getFloat(0.0f,1000.0f); float anotherRandomFloat = myRandom->get(0.0f,1000.0f);

default generator int a_random_int_between_0_and_1000 = TCOD_random_get_float(NULL,0,1000); another random generator TCOD_random_t my_random = TCOD_random_new(); float a_random_float_between_0_and_1000 = TCOD_random_get_float(my_random,0.0f,1000.0f);

default generator

a_random_int_between_0_and_1000 = libtcod.random_get_float(0,0,1000) another random generator

my_random = libtcod.random_new() a_random_float_between_0_and_1000 = libtcod.random_get_float(my_random,0.0,1000.0)

Parameters

mersenne – In the C and Python versions, the generator handler, returned by the initialization functions. If NULL, the default generator is used.
min, max – Range of values returned. Each time you call this function, you get a number between (including) min and max
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.

inline float get(float min, float max, float mean = 0.0f)¶

inline double getDouble(double min, double max, double mean = 0.0)¶

@noop random_use
@noop Getting a double
@brief To get a random double precision floating point number, using either the explicit or simplified API where applicable
@noop

explicit API: double TCODRandom::getDouble(double min, double max, double mean = 0.0f)

simplified API: double TCODRandom::get(double min, double max, double mean = 0.0f)

double TCOD_random_get_double(TCOD_random_t mersenne, double min, double max) double TCOD_random_get_double_mean(TCOD_random_t mersenne, double min, double max, double mean)

default generator TCODRandom * default = TCODRandom::getInstance(); int aRandomIntBetween0And1000 = default->getInt(0,1000); int anotherRandomInt = default->get(0,1000); another random generator TCODRandom *myRandom = new TCODRandom(); float aRandomFloatBetween0And1000 = myRandom->getFloat(0.0f,1000.0f); float anotherRandomFloat = myRandom->get(0.0f,1000.0f);

default generator int a_random_int_between_0_and_1000 = TCOD_random_get_float(NULL,0,1000); another random generator TCOD_random_t my_random = TCOD_random_new(); float a_random_float_between_0_and_1000 = TCOD_random_get_float(my_random,0.0f,1000.0f);

default generator

a_random_int_between_0_and_1000 = libtcod.random_get_float(0,0,1000) another random generator

my_random = libtcod.random_new() a_random_float_between_0_and_1000 = libtcod.random_get_float(my_random,0.0,1000.0)

Parameters

mersenne – In the C and Python versions, the generator handler, returned by the initialization functions. If NULL, the default generator is used.
min, max – Range of values returned. Each time you call this function, you get a number between (including) min and max
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.

inline double get(double min, double max, double mean = 0.0f)¶

TCODRandom *save() const¶

You can save the state of a generator with :

Parameters: mersenne – In the C and Python versions, the generator handler, returned by the initialization functions. If NULL, the default generator is used.

void restore(const TCODRandom *backup)¶

@noop random_use
@noop Restoring a saved state
@brief And restore it later. This makes it possible to get the same series of number several times with a single generator.
@noop void TCODRandom::restore(const TCODRandom *backup)
@noop void TCOD_random_restore(TCOD_random_t mersenne, TCOD_random_t backup)
@noop random_restore(mersenne, backup)
@noop# void TCODRandom::restore(TCODRandom backup)
@param mersenne In the C and Python versions, the generator handler, returned by the initialization functions. If NULL, the default generator is used.
@noop

default generator TCODRandom * default = TCODRandom::getInstance(); save the state TCODRandom *backup=default->save(); get a random number (or several) int number1 = default->getInt(0,1000); restore the state default->restore(backup); get a random number int number2 = default->getInt(0,1000); => number1 == number2

save default generator state TCOD_random_t backup=TCOD_random_save(NULL); get a random number int number1 = TCOD_random_get_float(NULL,0,1000); restore the state TCOD_random_restore(NULL,backup); get a random number int number2 = TCOD_random_get_float(NULL,0,1000); number1 == number2

save default generator state

backup=libtcod.random_save(0) get a random number

number1 = libtcod.random_get_float(0,0,1000) restore the state

libtcod.random_restore(0,backup) get a random number

number2 = libtcod.random_get_float(0,0,1000) number1 == number2

inline TCOD_dice_t dice(const char *s)¶

inline int diceRoll(TCOD_dice_t dice)¶

inline int diceRoll(const char *s)¶

inline TCOD_Random *get_data() noexcept¶

Return this objects TCOD_Random* pointer.

New in version 1.16.

inline const TCOD_Random *get_data() const noexcept¶

Public Static Functions

static TCODRandom *getInstance(void)¶

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).

Parameters: algo – The PRNG algorithm the generator should be using. Possible values are: TCOD_RNG_MT for Mersenne Twister, TCOD_RNG_CMWC for Complementary Multiply-With-Carry.

Protected Attributes

TCOD_Random *data = {}¶

Friends

friend class TCODNoise

friend class TCODHeightMap

friend class TCODNamegen

friend class TCODNameGenerator