Package de.gurkenlabs.litiengine

Class GameRandom

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

  • Method Summary

    Modifier and TypeMethodDescription
    doublechoose​(double... array)
    Chooses a pseudo-random element from the specified array.
    intchoose​(int... array)
    Chooses a pseudo-random element from the specified array.
    longchoose​(long... array)
    Chooses a pseudo-random element from the specified array.
    java.lang.Stringchoose​(java.lang.String... array)
    Chooses a pseudo-random element from the specified array.
    <T> Tchoose​(java.util.Collection<T> coll)
    Chooses a pseudo-random element from the specified collection.
    <T> Tchoose​(T[] array)
    Chooses a pseudo-random element from the specified array.
    intgetIndex​(double[] indexProbabilities)
    Returns a pseudo-random index that is distributed by the weights of the defined probability array.
    java.awt.geom.Point2DgetLocation​(double x, double y, double width, double height)
    Gets a pseudo-random location within the specified boundaries.
    java.awt.geom.Point2DgetLocation​(IEntity entity)
    Gets a pseudo-random location within the specified entity boundaries.
    java.awt.geom.Point2DgetLocation​(IMap map)
    Gets a pseudo-random location within the specified map boundaries.
    java.awt.geom.Point2DgetLocation​(java.awt.geom.Ellipse2D circle)
    Gets a pseudo-random location in the specified circle.
    java.awt.geom.Point2DgetLocation​(java.awt.geom.Line2D line)
    Gets a pseudo-random location on the specified line.
    java.awt.geom.Point2DgetLocation​(java.awt.geom.Point2D start, java.awt.geom.Point2D end)
    Gets a pseudo-random location on the line connecting the two specified points.
    java.awt.geom.Point2DgetLocation​(java.awt.geom.Rectangle2D rect)
    Gets a pseudo-random location within the specified boundaries.
    <T extends java.lang.Enum<?>>
    T    		next​(java.lang.Class<T> clazz) 
    java.lang.StringnextAlphabetic​(int length)
    Gets a pseudo-random alphabetic String of the specified length.
    java.lang.StringnextAlphabetic​(int length, boolean lowerCase)
    Gets a pseudo-random alphabetic String of the specified length.
    java.lang.StringnextAlphanumeric​(int length)
    Gets a pseudo-random alphanumeric String of the specified length.
    java.lang.StringnextAlphanumeric​(int length, boolean lowerCase)
    Gets a pseudo-random alphanumeric String of the specified length.
    java.lang.StringnextAlphanumeric​(int length, boolean digit, boolean lowerCase)
    Gets a pseudo-random alphanumeric String of the specified length.
    charnextAscii()
    Gets a pseudo-random char value.
    java.lang.StringnextAscii​(int length)
    Gets a pseudo-random String of the specified length.
    charnextChar()
    Gets a pseudo-random char value.
    charnextChar​(java.lang.String alphabet)
    Gets a pseudo-random char value from the specified alphabet.
    java.awt.ColornextColor​(java.awt.Color originalColor, float colorVariance, float alphaVariance)
    Returns a randomized variant of a given color.
    doublenextDouble​(double bound)
    Returns a pseudo-random double value between zero (inclusive) and the specified bound (exclusive).
    doublenextDouble​(double min, double bound)
    Returns a pseudo-random double value between the specified origin (inclusive) and the specified bound (exclusive).
    floatnextFloat​(float bound)
    Returns a pseudo-random float value between zero (inclusive) and the specified bound (exclusive).
    floatnextFloat​(float min, float bound)
    Returns a pseudo-random float value between the specified origin (inclusive) and the specified bound (exclusive).
    intnextInt​(int min, int bound)
    Returns a pseudo-random int value between the specified origin (inclusive) and the specified bound (exclusive).
    longnextLong​(long bound)
    Returns a pseudo-random long value between zero (inclusive) and the specified bound (exclusive).
    longnextLong​(long min, long bound)
    Returns a pseudo-random long value between the specified origin (inclusive) and the specified bound (exclusive).
    intnextSign()
    Gets a random algebraic sign that can be used to multiply values with it.
    booleanprobe​(double probability)
    Probes a pseudo-random value between 0.0 and 1.0 and checks whether it matches the specified probability.
    <T> java.util.Collection<T>sample​(java.util.Collection<T> collection, int amount, boolean replacement) 
    <T> T[]sample​(T[] array, int amount, boolean replacement) 
    voidsetSeed​(java.lang.String seed)
    Sets the seed of this random number generator using a String seed.
    voidshuffle​(double[] array)
    Shuffles the elements in the specified array.
    voidshuffle​(int[] array)
    Shuffles the elements in the specified array.
    voidshuffle​(long[] array)
    Shuffles the elements in the specified array.
    <T> voidshuffle​(java.util.List<T> coll)
    Shuffles the elements in the specified collection.
    <T> voidshuffle​(T[] array)
    Shuffles the elements in the specified array.
    doubleshuffleSign​(double value)
    Shuffles the algebraic sign of the specified double value.
    floatshuffleSign​(float value)
    Shuffles the algebraic sign of the specified float value.
    intshuffleSign​(int value)
    Shuffles the algebraic sign of the specified int value.
    longshuffleSign​(long value)
    Shuffles the algebraic sign of the specified long value.

    Methods inherited from class java.util.Random

    doubles, doubles, doubles, doubles, 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

  • Method Details

    • setSeed

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

    • sample

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

    • sample

      public <T> java.util.Collection<T> sample​(java.util.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 or 0 if the array is empty.
      Throws:
      java.lang.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 or 0 if the array is empty.
      Throws:
      java.lang.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 or 0 if the array is empty.
      Throws:
      java.lang.IllegalArgumentException - When the specified array is null or empty.

    • choose

      public java.lang.String choose​(java.lang.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 or 0 if the array is empty.
      Throws:
      java.lang.IllegalArgumentException - When the specified array is null or empty.

    • choose

      public <T> T choose​(java.util.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​(java.util.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:
      nextSign()

    • 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:
      nextSign()

    • 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:
      nextSign()

    • 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:
      nextSign()

    • 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:
      java.lang.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:
      java.lang.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:
      java.lang.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:
      java.lang.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:
      java.lang.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:
      java.lang.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:
      java.lang.IllegalArgumentException - if origin is greater than bound

    • next

      public <T extends java.lang.Enum<?>> T next​(java.lang.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 java.awt.geom.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 java.awt.geom.Point2D getLocation​(java.awt.geom.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 java.awt.geom.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:
      IEntity.getBoundingBox()

    • getLocation

      public java.awt.geom.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:
      IMap.getBounds()

    • getLocation

      public java.awt.geom.Point2D getLocation​(java.awt.geom.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 java.awt.geom.Point2D getLocation​(java.awt.geom.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:
      Line2D.getP1(), Line2D.getP2()

    • getLocation

      public java.awt.geom.Point2D getLocation​(java.awt.geom.Point2D start, java.awt.geom.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​(java.lang.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 java.lang.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 java.lang.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 java.lang.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 java.lang.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 java.lang.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 java.lang.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 java.awt.Color nextColor​(java.awt.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.