Package de.gurkenlabs.litiengine

Class GameRandom

java.lang.Object
java.util.Random
de.gurkenlabs.litiengine.GameRandom
All Implemented Interfaces:
Serializable, RandomGenerator
public final class GameRandom extends Random
A random number generator instance that provides enhanced functionalities for the java default Random implementation.
See Also:

  • Nested Class Summary

    Nested classes/interfaces inherited from interface java.util.random.RandomGenerator

    RandomGenerator.ArbitrarilyJumpableGenerator, RandomGenerator.JumpableGenerator, RandomGenerator.LeapableGenerator, RandomGenerator.SplittableGenerator, RandomGenerator.StreamableGenerator

  • Method Summary

    Modifier and Type
    Method
    Description
    double
    choose(double... array)
    Chooses a pseudo-random element from the specified array.
    int
    choose(int... array)
    Chooses a pseudo-random element from the specified array.
    long
    choose(long... array)
    Chooses a pseudo-random element from the specified array.
    String
    choose(String... array)
    Chooses a pseudo-random element from the specified array.
    <T> T
    choose(Collection<T> coll)
    Chooses a pseudo-random element from the specified collection.
    <T> T
    choose(T[] array)
    Chooses a pseudo-random element from the specified array.
    int
    getIndex(double[] indexProbabilities)
    Returns a pseudo-random index that is distributed by the weights of the defined probability array.
    Point2D
    getLocation(double x, double y, double width, double height)
    Gets a pseudo-random location within the specified boundaries.
    Point2D
    getLocation(IEntity entity)
    Gets a pseudo-random location within the specified entity boundaries.
    Point2D
    getLocation(IMap map)
    Gets a pseudo-random location within the specified map boundaries.
    Point2D
    getLocation(Ellipse2D circle)
    Gets a pseudo-random location in the specified circle.
    Point2D
    getLocation(Line2D line)
    Gets a pseudo-random location on the specified line.
    Point2D
    getLocation(Point2D start, Point2D end)
    Gets a pseudo-random location on the line connecting the two specified points.
    Point2D
    getLocation(Rectangle2D rect)
    Gets a pseudo-random location within the specified boundaries.
    <T extends Enum<?>>
    T
    next(Class<T> clazz)
     
    String
    nextAlphabetic(int length)
    Gets a pseudo-random alphabetic String of the specified length.
    String
    nextAlphabetic(int length, boolean lowerCase)
    Gets a pseudo-random alphabetic String of the specified length.
    String
    nextAlphanumeric(int length)
    Gets a pseudo-random alphanumeric String of the specified length.
    String
    nextAlphanumeric(int length, boolean lowerCase)
    Gets a pseudo-random alphanumeric String of the specified length.
    String
    nextAlphanumeric(int length, boolean digit, boolean lowerCase)
    Gets a pseudo-random alphanumeric String of the specified length.
    char
    nextAscii()
    Gets a pseudo-random char value.
    String
    nextAscii(int length)
    Gets a pseudo-random String of the specified length.
    char
    nextChar()
    Gets a pseudo-random char value.
    char
    nextChar(String alphabet)
    Gets a pseudo-random char value from the specified alphabet.
    Color
    nextColor(Color originalColor, float colorVariance, float alphaVariance)
    Returns a randomized variant of a given color.
    double
    nextDouble(double bound)
    Returns a pseudo-random double value between zero (inclusive) and the specified bound (exclusive).
    double
    nextDouble(double min, double bound)
    Returns a pseudo-random double value between the specified origin (inclusive) and the specified bound (exclusive).
    float
    nextFloat(float bound)
    Returns a pseudo-random float value between zero (inclusive) and the specified bound (exclusive).
    float
    nextFloat(float min, float bound)
    Returns a pseudo-random float value between the specified origin (inclusive) and the specified bound (exclusive).
    int
    nextInt(int min, int bound)
    Returns a pseudo-random int value between the specified origin (inclusive) and the specified bound (exclusive).
    long
    nextLong(long bound)
    Returns a pseudo-random long value between zero (inclusive) and the specified bound (exclusive).
    long
    nextLong(long min, long bound)
    Returns a pseudo-random long value between the specified origin (inclusive) and the specified bound (exclusive).
    int
    nextSign()
    Gets a random algebraic sign that can be used to multiply values with it.
    boolean
    probe(double probability)
    Probes a pseudo-random value between 0.0 and 1.0 and checks whether it matches the specified probability.
    <T> Collection<T>
    sample(Collection<T> collection, int amount, boolean replacement)
     
    <T> T[]
    sample(T[] array, int amount, boolean replacement)
     
    void
    setSeed(String seed)
    Sets the seed of this random number generator using a String seed.
    void
    shuffle(double[] array)
    Shuffles the elements in the specified array.
    void
    shuffle(int[] array)
    Shuffles the elements in the specified array.
    void
    shuffle(long[] array)
    Shuffles the elements in the specified array.
    <T> void
    shuffle(List<T> coll)
    Shuffles the elements in the specified collection.
    <T> void
    shuffle(T[] array)
    Shuffles the elements in the specified array.
    double
    shuffleSign(double value)
    Shuffles the algebraic sign of the specified double value.
    float
    shuffleSign(float value)
    Shuffles the algebraic sign of the specified float value.
    int
    shuffleSign(int value)
    Shuffles the algebraic sign of the specified int value.
    long
    shuffleSign(long value)
    Shuffles the algebraic sign of the specified long value.

    Methods inherited from class java.util.Random

    doubles, doubles, doubles, doubles, from, ints, ints, ints, ints, longs, longs, longs, longs, next, nextBoolean, nextBytes, nextDouble, nextFloat, nextGaussian, nextInt, nextInt, nextLong, setSeed

    Methods inherited from class java.lang.Object

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

    Methods inherited from interface java.util.random.RandomGenerator

    isDeprecated, nextExponential, nextGaussian

  • Method Details

    • setSeed

      public void setSeed(String seed)
      Sets the seed of this random number generator using a String seed.
      Parameters:
      seed - The initial seed.
      See Also:

    • sample

      public <T> T[] sample(T[] array, int amount, boolean replacement)

    • sample

      public <T> Collection<T> sample(Collection<T> collection, int amount, boolean replacement)

    • choose

      public <T> T choose(T[] array)
      Chooses a pseudo-random element from the specified array.
      Type Parameters:
      T - The type of the elements in the array.
      Parameters:
      array - The array to choose from.
      Returns:
      A pseudo-random element from the array or null if the array is empty.

    • choose

      public int choose(int... array)
      Chooses a pseudo-random element from the specified array.
      Parameters:
      array - The array to choose from.
      Returns:
      A pseudo-random element from the array.
      Throws:
      IllegalArgumentException - When the specified array is null or empty.

    • choose

      public long choose(long... array)
      Chooses a pseudo-random element from the specified array.
      Parameters:
      array - The array to choose from.
      Returns:
      A pseudo-random element from the array.
      Throws:
      IllegalArgumentException - When the specified array is null or empty.

    • choose

      public double choose(double... array)
      Chooses a pseudo-random element from the specified array.
      Parameters:
      array - The array to choose from.
      Returns:
      A pseudo-random element from the array.
      Throws:
      IllegalArgumentException - When the specified array is null or empty.

    • choose

      public String choose(String... array)
      Chooses a pseudo-random element from the specified array.
      Parameters:
      array - The array to choose from.
      Returns:
      A pseudo-random element from the array.
      Throws:
      IllegalArgumentException - When the specified array is null or empty.

    • choose

      public <T> T choose(Collection<T> coll)
      Chooses a pseudo-random element from the specified collection.
      Type Parameters:
      T - The type of the elements in the collection.
      Parameters:
      coll - The collection to choose from.
      Returns:
      A pseudo-random element from the array or null if the collection is empty.

    • shuffle

      public <T> void shuffle(T[] array)
      Shuffles the elements in the specified array.
      Type Parameters:
      T - The type of the elements in the collection.
      Parameters:
      array - The array to be shuffled.

    • shuffle

      public void shuffle(int[] array)
      Shuffles the elements in the specified array.
      Parameters:
      array - The array to be shuffled.

    • shuffle

      public void shuffle(long[] array)
      Shuffles the elements in the specified array.
      Parameters:
      array - The array to be shuffled.

    • shuffle

      public void shuffle(double[] array)
      Shuffles the elements in the specified array.
      Parameters:
      array - The array to be shuffled.

    • shuffle

      public <T> void shuffle(List<T> coll)
      Shuffles the elements in the specified collection.
      Type Parameters:
      T - The type of the elements in the collection.
      Parameters:
      coll - The collection to be shuffled.

    • nextSign

      public int nextSign()
      Gets a random algebraic sign that can be used to multiply values with it.

      This either returns 1 or -1 depending on the random outcome.

      Returns:
      A random sign for algebraic operations.

    • shuffleSign

      public int shuffleSign(int value)
      Shuffles the algebraic sign of the specified int value.
      Parameters:
      value - The value to shuffle.
      Returns:
      Either the specified value; or its negative equivalent (multiplied by -1).
      See Also:

    • shuffleSign

      public float shuffleSign(float value)
      Shuffles the algebraic sign of the specified float value.
      Parameters:
      value - The value to shuffle.
      Returns:
      Either the specified value; or its negative equivalent (multiplied by -1).
      See Also:

    • shuffleSign

      public long shuffleSign(long value)
      Shuffles the algebraic sign of the specified long value.
      Parameters:
      value - The value to shuffle.
      Returns:
      Either the specified value; or its negative equivalent (multiplied by -1).
      See Also:

    • shuffleSign

      public double shuffleSign(double value)
      Shuffles the algebraic sign of the specified double value.
      Parameters:
      value - The value to shuffle.
      Returns:
      Either the specified value; or its negative equivalent (multiplied by -1).
      See Also:

    • nextLong

      public long nextLong(long bound)
      Returns a pseudo-random long value between zero (inclusive) and the specified bound (exclusive).
      Parameters:
      bound - the upper bound (exclusive). Must be positive.
      Returns:
      a pseudo-random long value between zero (inclusive) and the bound (exclusive)
      Throws:
      IllegalArgumentException - if bound is not positive

    • nextLong

      public long nextLong(long min, long bound)
      Returns a pseudo-random long value between the specified origin (inclusive) and the specified bound (exclusive).
      Parameters:
      min - the least value returned
      bound - the upper bound (exclusive)
      Returns:
      a pseudo-random long value between the origin (inclusive) and the bound (exclusive)
      Throws:
      IllegalArgumentException - if origin is greater than bound

    • nextDouble

      public double nextDouble(double bound)
      Returns a pseudo-random double value between zero (inclusive) and the specified bound (exclusive).
      Parameters:
      bound - the upper bound (exclusive). Must be positive.
      Returns:
      a pseudo-random double value between zero (inclusive) and the bound (exclusive)
      Throws:
      IllegalArgumentException - if bound is not positive

    • nextDouble

      public double nextDouble(double min, double bound)
      Returns a pseudo-random double value between the specified origin (inclusive) and the specified bound (exclusive).
      Parameters:
      min - the least value returned
      bound - the upper bound (exclusive)
      Returns:
      a pseudo-random double value between the origin (inclusive) and the bound (exclusive)
      Throws:
      IllegalArgumentException - if origin is greater than bound

    • nextFloat

      public float nextFloat(float bound)
      Returns a pseudo-random float value between zero (inclusive) and the specified bound (exclusive).
      Parameters:
      bound - the upper bound (exclusive). Must be positive.
      Returns:
      a pseudo-random float value between zero (inclusive) and the bound (exclusive)
      Throws:
      IllegalArgumentException - if bound is not positive

    • nextFloat

      public float nextFloat(float min, float bound)
      Returns a pseudo-random float value between the specified origin (inclusive) and the specified bound (exclusive).
      Parameters:
      min - the least value returned
      bound - the upper bound (exclusive)
      Returns:
      a pseudo-random float value between the origin (inclusive) and the bound (exclusive)
      Throws:
      IllegalArgumentException - if origin is greater than bound

    • nextInt

      public int nextInt(int min, int bound)
      Returns a pseudo-random int value between the specified origin (inclusive) and the specified bound (exclusive).
      Parameters:
      min - the least value returned
      bound - the upper bound (exclusive)
      Returns:
      a pseudo-random int value between the origin (inclusive) and the bound (exclusive)
      Throws:
      IllegalArgumentException - if origin is greater than bound

    • next

      public <T extends Enum<?>> T next(Class<T> clazz)

    • probe

      public boolean probe(double probability)
      Probes a pseudo-random value between 0.0 and 1.0 and checks whether it matches the specified probability.

      Example: if the specified probability is 0.5, the sampled value needs to be less than or equal to the specified value in order for this method to return true.

      Parameters:
      probability - The probability to check.
      Returns:
      True if the sampled value matches the probability; otherwise false.

    • getIndex

      public int getIndex(double[] indexProbabilities)
      Returns a pseudo-random index that is distributed by the weights of the defined probability array. The index probabilities must sum up to 1;
      Parameters:
      indexProbabilities - The index with the probabilities for the related index.
      Returns:
      A random index within the range of the specified array.

    • getLocation

      public Point2D getLocation(double x, double y, double width, double height)
      Gets a pseudo-random location within the specified boundaries.
      Parameters:
      x - The min-x coordinate of the boundaries.
      y - The min-y coordinate of the boundaries.
      width - The width of the boundaries.
      height - The height of the boundaries.
      Returns:
      A pseudo-random location within the specified bounds.

    • getLocation

      public Point2D getLocation(Rectangle2D rect)
      Gets a pseudo-random location within the specified boundaries.
      Parameters:
      rect - The rectangle that defines the boundaries.
      Returns:
      A pseudo-random location within the specified bounds.

    • getLocation

      public Point2D getLocation(IEntity entity)
      Gets a pseudo-random location within the specified entity boundaries.
      Parameters:
      entity - The entity that defines the boundaries.
      Returns:
      A pseudo-random location within the specified bounds.
      See Also:

    • getLocation

      public Point2D getLocation(IMap map)
      Gets a pseudo-random location within the specified map boundaries.
      Parameters:
      map - The map that defines the boundaries.
      Returns:
      A pseudo-random location within the specified bounds.
      See Also:

    • getLocation

      public Point2D getLocation(Ellipse2D circle)
      Gets a pseudo-random location in the specified circle.
      Parameters:
      circle - The circle that defines the boundaries.
      Returns:
      A pseudo-random location on the specified circle.

    • getLocation

      public Point2D getLocation(Line2D line)
      Gets a pseudo-random location on the specified line.
      Parameters:
      line - The line that defines the boundaries.
      Returns:
      A pseudo-random location on the specified line.
      See Also:

    • getLocation

      public Point2D getLocation(Point2D start, Point2D end)
      Gets a pseudo-random location on the line connecting the two specified points.
      Parameters:
      start - The start point.
      end - The end point.
      Returns:
      A pseudo-random location on the line connecting the two specified points.

    • nextChar

      public char nextChar()
      Gets a pseudo-random char value.
      Returns:
      A pseudo-random character.

    • nextChar

      public char nextChar(String alphabet)
      Gets a pseudo-random char value from the specified alphabet.
      Parameters:
      alphabet - The alphabet to chose the character from.
      Returns:
      A pseudo-random character from the specified alphabet.

    • nextAscii

      public char nextAscii()
      Gets a pseudo-random char value.
      Returns:
      A pseudo-random character.

    • nextAscii

      public String nextAscii(int length)
      Gets a pseudo-random String of the specified length.

      Characters will be chosen from the set of characters whose ASCII value is between 32 and 126 (inclusive)

      Parameters:
      length - The length of the String.
      Returns:
      A pseudo-random ASCII String.

    • nextAlphanumeric

      public String nextAlphanumeric(int length)
      Gets a pseudo-random alphanumeric String of the specified length.
      Parameters:
      length - The length of the String.
      Returns:
      A pseudo-random alphanumeric String.

    • nextAlphanumeric

      public String nextAlphanumeric(int length, boolean lowerCase)
      Gets a pseudo-random alphanumeric String of the specified length.
      Parameters:
      length - The length of the String.
      lowerCase - Indicates whether lower-case letters will be included in the String.
      Returns:
      A pseudo-random alphanumeric String.

    • nextAlphanumeric

      public String nextAlphanumeric(int length, boolean digit, boolean lowerCase)
      Gets a pseudo-random alphanumeric String of the specified length.
      Parameters:
      length - The length of the String.
      digit - Indicates whether digits will be included in the string.
      lowerCase - Indicates whether lower-case letters will be included in the String.
      Returns:
      A pseudo-random alphanumeric String.

    • nextAlphabetic

      public String nextAlphabetic(int length)
      Gets a pseudo-random alphabetic String of the specified length.
      Parameters:
      length - The length of the String.
      Returns:
      A pseudo-random alphabetic String.

    • nextAlphabetic

      public String nextAlphabetic(int length, boolean lowerCase)
      Gets a pseudo-random alphabetic String of the specified length.
      Parameters:
      length - The length of the String.
      lowerCase - Indicates whether lower-case letters will be included in the String.
      Returns:
      A pseudo-random alphabetic String.

    • nextColor

      public Color nextColor(Color originalColor, float colorVariance, float alphaVariance)
      Returns a randomized variant of a given color.
      Parameters:
      originalColor - The original color to be modified.
      colorVariance - The float value between 0 and 1 defining how strong the new Color's RGB values will deviate from the original Color.
      alphaVariance - The float value between 0 and 1 defining how strong the new Color's Alpha will deviate from the original Color.
      Returns:
      A pseudo-randomized variant of the original Color.