libtcoddocumentation

7.1. Creating a generator

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

static TCODRandom * TCODRandom::getInstance (void)

TCOD_random_t TCOD_random_get_instance (void)

random_get_instance ()

static TCODRandom TCODRandom::getInstance()

ParameterDescription
algoThe PRNG algorithm the generator should be using. Possible values are:
* TCOD_RNG_MT for Mersenne Twister,
* TCOD_RNG_CMWC for Complementary Multiply-With-Carry.

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.

TCODRandom::TCODRandom (TCOD_random_algo_t algo = TCOD_RNG_CMWC)

TCOD_random_t TCOD_random_new (TCOD_random_algo_t algo)

random_new (algo = RNG_CMWC)

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

ParameterDescription
algoThe PRNG algorithm the generator should be using.

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)

TCODRandom::TCODRandom (uint32 seed, TCOD_random_algo_t algo = TCOD_RNG_CMWC);

TCOD_random_t TCOD_random_new_from_seed (TCOD_random_algo_t algo, uint32 seed);

random_new_from_seed(seed, algo=RNG_CMWC)

TCODRandom::TCODRandom(uint32 seed) // Defaults to ComplementaryMultiplyWithCarry
TCODRandom::TCODRandom(uint32 seed, TCODRandomType algo)

ParameterDescription
seedThe 32 bits seed used to initialize the generator. Two generators created with the same seed will generate the same set of pseudorandom numbers.
algoThe PRNG algorithm the generator should be using.
Example:

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


Destroying a RNG

To release ressources used by a generator, use those functions :
NB : do not delete the default random generator !

TCODRandom::~TCODRandom()

void TCOD_random_delete(TCOD_random_t mersenne)

random_delete(mersenne)

void TCODRandom::Dispose()

ParameterDescription
mersenneIn the C and Python versions, the generator handler, returned by the initialization functions.
Example:

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