vooga.engine.resource.random
Class Randomizer

java.lang.Object
  vooga.engine.resource.random.Randomizer

public class Randomizer
extends java.lang.Object

Manages random number generation for the game using a primary random number generator. The majority if not all of the game functions should use the primary random number generator in order to facilitate reproducibility and replayability for game sessions. The available random value are: integers uniformly distributed across the full range integers uniformly distributed across a range of 0 to some maximum value integers uniformly distributed across a range with a minimum and maximum value longs uniformly distributed across the full range longs uniformly distributed across a range of 0 to some maximum value longs uniformly distributed across a range with a minimum and maximum value doubles uniformly distributed across from 0 inclusive to 1 exclusive doubles uniformly distributed across a range of 0 inclusive to some maximum value exclusive doubles uniformly distributed across a range with a minimum inclusive and maximum exclusive value floats uniformly distributed across from 0 inclusive to 1 exclusive floats uniformly distributed across a range of 0 inclusive to some maximum value exclusive floats uniformly distributed across a range with a minimum inclusive and maximum exclusive value booleans doubles in a standardized Gaussian distribution Functionality is included for retrieving use of past game seeds in order to allow for recreation of past random variable usage. Seeds can either be retrieved based on unique string ids or using a chronological list of used seeds which also includes unnamed seeds and the number of times each seed was used. The most basic seed reuse functionality of starting over using the current seed is also available. If at any point random number generation is required but the use of the primary number generator would compromise the replayability, secondary random number generators are available. For instance, particle effects based on random movement might require random number generation, but the exact replication of the movement of the particles is not required for replayability. Furthermore, using the primary number generator could cause potential problems in off-setting future random number values if somehow the particle requires the use of one more random number in a replay. To avoid this issue, one could create implement a secondary random number generator, called a random path, which is referred to by a unique string id. Then, in this example, particle movement could use that USID to create a sequence of random variables on a the new random path without affecting the primary random number generator. These random paths do not have the same retrieval functionality as the primary generator. The random number generation is based on the java.util.Random class.

Constructor Summary

Randomizer()

Method Summary

static void	createRandomPath(java.lang.String pathID) Create a new random path/secondary random number generator referenced by a unique string id and seeded with a value based on the current system time.
static void	createRandomPath(java.lang.String pathID, java.lang.Long seed) Create a new random path/secondary random number generator referenced by a unique string id and seeded with a given value
static long	generateSeed() Returns a value to be used for seeding based on the current system time.
static java.util.List<java.lang.String>	getUsedSeedNames() Return the USIDs of all the seeds used this game in chronological order.
static java.lang.String	getUsedSeedsCSV() Returns a comma separated value String of the last used seed values and the corresponding unique string IDs of those seeds in chronological order.
static java.util.List<java.lang.Long>	getUsedSeedVals() Return the last used seed values seeded to the primary random number generator in chronological order.
static boolean	nextBoolean() Returns a random boolean using the primary number generator.
static boolean	nextBoolean(java.lang.String pathID) Returns a random boolean using the a specified random path
static double	nextDouble(double... range) Returns a random double using the primary number generator.
static double	nextDouble(java.lang.String pathID, double... range) Returns a random double using a specified random path.
static float	nextFloat(float... range) Returns a random float using the primary number generator.
static float	nextFloat(java.lang.String pathID, float... range) Returns a random float using a specified random path.
static double	nextGaussian() Returns a random double from a standardized Gaussian distribution using the primary random number generator.
static double	nextGaussian(java.lang.String pathID) Returns a random double from a standardized Gaussian distribution using a specified random path.
static int	nextInt(java.lang.Integer... range) Returns a random integer using the primary number generator.
static int	nextInt(java.lang.String pathID, java.lang.Integer... range) Returns a random integer using a specified random path.
static long	nextLong(long... range) Returns a random long using the primary number generator.
static long	nextLong(java.lang.String pathID, long... range) Returns a random long using a specified random path.
static void	resetSeed() Reset the primary random number generator to start over using its current seed value which allows replication of the sequence of random numbers used since the last time the seed was changed.
static void	resetSeed(java.lang.String seedUSID) Reset the primary random number generator to start over using its the seed value corresponding to a unique string id which allows replication of the sequence of random numbers from that seed.
static void	setSeed(long seed) Set the seed of the primary random number generator to the given seed value.
static void	setSeed(long seed, java.lang.String seedUSID) Set the seed of the primary random number generator to the given seed value which will be retrievable using a unique string identification for the seed.
static void	setSeed(long seed, java.lang.String seedUSID, boolean overwrite) Set the seed of the primary random number generator to the given seed value which will be retrievable using a unique string identification for the seed.
static void	setSeed(java.lang.String seedUSID) Set the seed of the primary random number generator to some seed value which will be retrievable using a unique string identification for the seed.
static void	setSeed(java.lang.String seedUSID, boolean overwrite) Set the seed of the primary random number generator to some seed value which will be retrievable using a unique string identification for the seed.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Randomizer

public Randomizer()

Method Detail

createRandomPath

public static void createRandomPath(java.lang.String pathID)

Create a new random path/secondary random number generator referenced by a unique string id and seeded with a value based on the current system time.

Parameters:

pathID - the unique string identification of the random path

createRandomPath

public static void createRandomPath(java.lang.String pathID,
                                    java.lang.Long seed)

Create a new random path/secondary random number generator referenced by a unique string id and seeded with a given value

Parameters:

pathID - the unique string identification of the random path

seed - the value to seed the random number generator with

generateSeed

public static long generateSeed()

Returns a value to be used for seeding based on the current system time. Note that this value is not assigned to any random number generator by this method

Returns:

a seed value for use in a random number generator

setSeed

public static void setSeed(long seed)

Set the seed of the primary random number generator to the given seed value. This value will not be retrievable by any name.

Parameters:

seed - the value to seed the primary number generator

setSeed

public static void setSeed(java.lang.String seedUSID)

Set the seed of the primary random number generator to some seed value which will be retrievable using a unique string identification for the seed. If the seed USID is already in use, no change will be made.

Parameters:

seedUSID - unique string ID for the seed

setSeed

public static void setSeed(java.lang.String seedUSID,
                           boolean overwrite)

Set the seed of the primary random number generator to some seed value which will be retrievable using a unique string identification for the seed. If the seed USID is already in use, no change will be made unless overwrite is set to true in which case the former value will be overwritten the generator will be set.

Parameters:

seedUSID - unique string ID for the seed

setSeed

public static void setSeed(long seed,
                           java.lang.String seedUSID)

Set the seed of the primary random number generator to the given seed value which will be retrievable using a unique string identification for the seed. If the seed USID is already in use, no change will be made.

Parameters:

seed - the value to seed the primary number generator

seedUSID - unique string ID for the seed

setSeed

public static void setSeed(long seed,
                           java.lang.String seedUSID,
                           boolean overwrite)

Set the seed of the primary random number generator to the given seed value which will be retrievable using a unique string identification for the seed. If the seed USID is already in use, no change will be made unless overwrite is set to true in which case the former value will be overwritten the generator will be set.

Parameters:

seed - the value to seed the primary number generator

seedUSID - unique string ID for the seed

resetSeed

public static void resetSeed()

Reset the primary random number generator to start over using its current seed value which allows replication of the sequence of random numbers used since the last time the seed was changed.

resetSeed

public static void resetSeed(java.lang.String seedUSID)

Reset the primary random number generator to start over using its the seed value corresponding to a unique string id which allows replication of the sequence of random numbers from that seed.

Parameters:

seedUSID - the unique string id of the seed to set the generator to

getUsedSeedNames

public static java.util.List<java.lang.String> getUsedSeedNames()

Return the USIDs of all the seeds used this game in chronological order. This list can be analyzed to determine where the seed might be set for a replay.

Returns:

a List of the USID of the seeds used this session in chronological order

getUsedSeedVals

public static java.util.List<java.lang.Long> getUsedSeedVals()

Return the last used seed values seeded to the primary random number generator in chronological order. This list can be analyzed to determine where the seed might be set for a replay.

Returns:

a list of the used seed values for this session in chronological order

getUsedSeedsCSV

public static java.lang.String getUsedSeedsCSV()

Returns a comma separated value String of the last used seed values and the corresponding unique string IDs of those seeds in chronological order. The first value is the seeds USID, then a comma, then the corresponding seed value. This pair is then followed by a newline character.

Returns:

nextInt

public static int nextInt(java.lang.Integer... range)
                   throws RandomizerException

Returns a random integer using the primary number generator. No arguments will return an integer from the whole range of integers. One int will return an integer between zero and that value. Two ints will return an integer between the two values. The minimum must be specified first.

Parameters:

range - leave blank for random int, or specify a maximum, or specify a range

Returns:

random integer

Throws:

RandomizerException

nextLong

public static long nextLong(long... range)
                     throws RandomizerException

Returns a random long using the primary number generator. No arguments will return a long from the whole range of longs. One long will return a long between zero and that value. Two longs will return a long between the two values. The minimum must be specified first.

Parameters:

range - leave blank for random long, or specify a maximum, or specify a range

Returns:

random long

Throws:

RandomizerException

nextDouble

public static double nextDouble(double... range)
                         throws RandomizerException

Returns a random double using the primary number generator. No arguments will return a double from [0,1]. One double will return a double from [0, max) . Two doubles will return a double from [min, max). The minimum must be specified first.

Parameters:

range - leave blank for random double, or specify a maximum, or specify a range

Returns:

random double

Throws:

RandomizerException

nextFloat

public static float nextFloat(float... range)
                       throws RandomizerException

Returns a random float using the primary number generator. No arguments will return a float from [0,1]. One float will return a float from [0, max) . Two floats will return a float from [min, max). The minimum must be specified first.

Parameters:

range - leave blank for random float, or specify a maximum, or specify a range

Returns:

random float

Throws:

RandomizerException

nextBoolean

public static boolean nextBoolean()

Returns a random boolean using the primary number generator.

Returns:

random true or false value

nextGaussian

public static double nextGaussian()

Returns a random double from a standardized Gaussian distribution using the primary random number generator.

Returns:

double from Gaussian distribution

nextInt

public static int nextInt(java.lang.String pathID,
                          java.lang.Integer... range)
                   throws RandomizerException

Returns a random integer using a specified random path. No additional arguments will return an integer from the whole range of integers. One int will return an integer between zero and that value. Two ints will return an integer between the two values. The minimum must be specified first.

Parameters:

pathID - the unique string id of the desired random path

range - leave blank for random int, or specify a maximum, or specify a range

Returns:

random integer

Throws:

RandomizerException

nextLong

public static long nextLong(java.lang.String pathID,
                            long... range)
                     throws RandomizerException

Returns a random long using a specified random path. No additional arguments will return a long from the whole range of longs. One long will return a long between zero and that value. Two longs will return a long between the two values. The minimum must be specified first.

Parameters:

pathID - the unique string id of the desired random path

range - leave blank for random long, or specify a maximum, or specify a range

Returns:

random long

Throws:

RandomizerException

nextDouble

public static double nextDouble(java.lang.String pathID,
                                double... range)
                         throws RandomizerException

Returns a random double using a specified random path. No additional arguments will return a double from [0,1]. One double will return a double from [0, max) . Two doubles will return a double from [min, max). The minimum must be specified first.

Parameters:

pathID - the unique string id of the desired random path

range - leave blank for random double, or specify a maximum, or specify a range

Returns:

random double

Throws:

RandomizerException

nextFloat

public static float nextFloat(java.lang.String pathID,
                              float... range)
                       throws RandomizerException

Returns a random float using a specified random path. No additional arguments will return a float from [0,1]. One float will return a float from [0, max) . Two floats will return a float from [min, max). The minimum must be specified first.

Parameters:

pathID - the unique string id of the desired random path

range - leave blank for random float, or specify a maximum, or specify a range

Returns:

random float

Throws:

RandomizerException

nextBoolean

public static boolean nextBoolean(java.lang.String pathID)

Returns a random boolean using the a specified random path

Parameters:

pathID - the unique string id of the desired random path

Returns:

random true or false value

nextGaussian

public static double nextGaussian(java.lang.String pathID)

Returns a random double from a standardized Gaussian distribution using a specified random path.

Parameters:

pathID - the unique string id of the desired random path

Returns:

double from Gaussian distribution