/ 
TCOD-0.009
River stage zero No dependents
/ TCOD::Random

NAME

TCOD::Random - A fast and high quality pseudo-random number generator

SYNOPSIS

use TCOD;

my $rng    = TCOD::Random->new( TCOD::RNG_CMWC );
my $backup = $rng->save;

# Generate 11 random numbers between 0 and 10 inclusive
my @numbers = map $rng->get_int( 0, 10 ), 0 .. 10;

$rng->restore( $backup );

# Generate _the same_ sequence of numbers after restoring state
my @more_numbers = map $rng->get_int( 0, 10 ), 0 .. 10;

DESCRIPTION

Perl already has great random generators available. 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 this library.

METHODS

get_instance

$rng = TCOD::Random->get_instance;

The simplest way to get random number is to use the default generator. The first time you get this generator, it is initialised by calling new. Then, on successive calls, this function returns the same generator.

The default instance uses the TCOD::RNG_CMWC algorithm since libtcod 1.5.0.

new

$rng = TCOD::Random->new( $algo );

Initialise a random number generator with the specified algorithm. The value in $algo must be one of the RandomAlgo enum.

This function will internally call new_from_seed with the current timestamp as the seed (which means that calling it twice in the same second will return the same generator).

new_from_seed

$rng = TCOD::Random->new_from_seed( $algo, $seed );

Create a new pseudo-random number generator with the specified algorithm and seed. The seed should be a 32-bit integer, while the algorithm must be a value in the RandomAlgo enum.

save

$backup = $rng->save;

Save the state of the generator.

restore

$rng->restore( $backup );

Restore a random number generator to a previous state. See save for how to capture this backup.

set_distribution

$rng->set_distribution( $distribution );

Set the distribution used by this pseudo-random number generator. The distribution must be one from the Distribution enum, where TCOD::DISTRIBUTION_LINEAR is the default.

All random number getters called on this generator will then use this distribution automatically to fetch your random numbers.

Some functions (eg. get_int_mean 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.

When using these distributions, the selected mean will have the highest probability of appearing:

  • TCOD::DISTRIBUTION_LINEAR

  • TCOD::DISTRIBUTION_GAUSSIAN

  • TCOD::DISTRIBUTION_GAUSSIAN_RANGE

When using these distributions, the selected mean will have the lowest probability of appearing:

  • TCOD::DISTRIBUTION_GAUSSIAN_INVERSE

  • TCOD::DISTRIBUTION_GAUSSIAN_RANGE_INVERSE

SEE ALSO

TCOD
TCOD::Noise

COPYRIGHT AND LICENSE

Copyright 2021 José Joaquín Atria

This library is free software; you can redistribute it and/or modify it under the Artistic License 2.0.