Package squidpony.squidmath

Class DharmaRNG

java.lang.Object
squidpony.squidmath.RNG
squidpony.squidmath.DharmaRNG
All Implemented Interfaces:
Serializable, IRNG, RandomnessSource
public class DharmaRNG
extends RNG
implements Serializable
An alteration to a RandomnessSource that attempts to produce values that are perceived as fair to an imperfect user.

This takes a RandomnessSource, defaulting to a DiverRNG, and uses it to generate random values, but tracks the total and compares it to the potential total of a generator of only numbers with a desired value (default 0.54, so it compares against a sequence of all 0.54). If the current generated total is too high or low compared to the desired total, the currently used seed is possibly changed, the generated number is moved in the direction of the desired fairness, and it returns that instead of the number that would have pushed the current generated total beyond the desired threshold. The new number, if one is changed, will always be closer to the desired fairness. This is absolutely insecure for cryptographic purposes, but should seem more "fair" to a player than a random number generator that seeks to be truly random. You can create multiple DharmaRNG objects with different fairness values and seeds, and use favorable generators (with fairness greater than 0.54) for characters that need an easier time, or unfavorable generators if you want the characters that use that RNG to be impeded somewhat. The name comes from the Wheel of Dharma. This class currently will have a slight bias toward lower numbers with many RNGs unless fairness is tweaked; 0.54 can be used as a stand-in because 0.5 leans too low.

You can get values from this generator with: nextDouble(), nextInt(), nextLong(), and the bounded variants on each of those.

You can alter the tracking information or requested fairness with resetFortune(), setFairness(double), and getFairness(). Created by Tommy Ettinger on 5/2/2015.

See Also:
Serialized Form

  • Constructor Details

    • DharmaRNG

      public DharmaRNG()
      Constructs a DharmaRNG with a pseudo-random seed from Math.random().

    • DharmaRNG

      public DharmaRNG​(long seed)
      Construct a new DharmaRNG with the given seed.
      Parameters:
      seed - used to seed the default RandomnessSource.

    • DharmaRNG

      public DharmaRNG​(long seed, double fairness)
      Construct a new DharmaRNG with the given seed.
      Parameters:
      seed - used to seed the default RandomnessSource.
      fairness - the desired fairness metric, which must be between 0.0 and 1.0

    • DharmaRNG

      public DharmaRNG​(CharSequence seedString)
      String-seeded constructor; uses a platform-independent hash of the String (it does not use String.hashCode) as a seed for DiverRNG, which is of high quality, but low period (which rarely matters for games), and has good speed, tiny state size, and excellent 64-bit number generation.
      Parameters:
      seedString - a String as a seed

    • DharmaRNG

      public DharmaRNG​(String seedString, double fairness)
      String-seeded constructor; uses a platform-independent hash of the String (it does not use String.hashCode) as a seed for DiverRNG, which is of high quality, but low period (which rarely matters for games), and has good speed, tiny state size, and excellent 64-bit number generation.
      Parameters:
      seedString - a String as a seed

    • DharmaRNG

      public DharmaRNG​(RandomnessSource rs)
      Construct a new DharmaRNG with the given seed.
      Parameters:
      rs - the implementation used to generate random bits.

    • DharmaRNG

      public DharmaRNG​(RandomnessSource rs, double fairness)
      Construct a new DharmaRNG with the given seed.
      Parameters:
      rs - the implementation used to generate random bits.
      fairness - the desired fairness metric, which must be between 0.0 and 1.0

  • Method Details

    • nextDouble

      public double nextDouble()
      Generate a random double, altering the result if recently generated results have been leaning away from this class' fairness value.
      Specified by:
      nextDouble in interface IRNG
      Overrides:
      nextDouble in class RNG
      Returns:
      a double between 0.0 (inclusive) and 1.0 (exclusive)

    • nextInt

      public int nextInt​(int bound)
      Returns a random integer below the given bound, or 0 if the bound is 0 or negative. Affects the current fortune.
      Specified by:
      nextInt in interface IRNG
      Overrides:
      nextInt in class RNG
      Parameters:
      bound - the upper bound (exclusive)
      Returns:
      the found number

    • nextInt

      public int nextInt()
      Returns a random integer, which may be any positive or negative value. Affects the current fortune.
      Specified by:
      nextInt in interface IRNG
      Overrides:
      nextInt in class RNG
      Returns:
      A random int (can be any int, without restriction)

    • nextLong

      public long nextLong()
      Returns a random long, which may be any positive or negative value. Affects the current fortune.
      Specified by:
      nextLong in interface IRNG
      Specified by:
      nextLong in interface RandomnessSource
      Overrides:
      nextLong in class RNG
      Returns:
      A random long (can be any long, without restriction)

    • nextLong

      public long nextLong​(long bound)
      Returns a random long below the given bound, or 0 if the bound is 0 or negative.
      Specified by:
      nextLong in interface IRNG
      Overrides:
      nextLong in class RNG
      Parameters:
      bound - the upper bound (exclusive)
      Returns:
      the found number

    • getFairness

      public double getFairness()
      Gets the measure that this class uses for RNG fairness, defaulting to 0.54 (always between 0.0 and 1.0).
      Returns:
      the current fairness metric.

    • setFairness

      public void setFairness​(double fairness)
      Sets the measure that this class uses for RNG fairness, which must always be between 0.0 and 1.0, and will be set to 0.54 if an invalid value is passed.
      Parameters:
      fairness - the desired fairness metric, which must be 0.0 <= fairness < 1.0

    • getFortune

      public double getFortune()
      Gets the status of the fortune used when calculating fairness adjustments.
      Returns:
      the current value used to determine whether the results should be adjusted toward fairness.

    • resetFortune

      public void resetFortune()
      Resets the stored history this RNG uses to try to ensure fairness.

    • next

      public int next​(int bits)
      Description copied from class: RNG
      Get up to 32 bits (inclusive) of random output; the int this produces will not require more than bits bits to represent.
      Specified by:
      next in interface IRNG
      Specified by:
      next in interface RandomnessSource
      Overrides:
      next in class RNG
      Parameters:
      bits - the number of bits to be returned
      Returns:
      a random int of the number of bits specified.

    • between

      public long between​(long min, long max)
      Returns a value between min (inclusive) and max (exclusive).

      The inclusive and exclusive behavior is to match the behavior of the similar method that deals with floating point values.

      Specified by:
      between in interface IRNG
      Overrides:
      between in class RNG
      Parameters:
      min - the minimum bound on the return value (inclusive)
      max - the maximum bound on the return value (exclusive)
      Returns:
      the found value

    • nextIntHasty

      public int nextIntHasty​(int bound)
      Returns a random non-negative integer below the given bound, or 0 if the bound is 0. Uses a slightly optimized technique. This method is considered "hasty" since it should be faster than nextInt() doesn't check for "less-valid" bounds values. It also has undefined behavior if bound is negative, though it will probably produce a negative number (just how negative is an open question).
      Overrides:
      nextIntHasty in class RNG
      Parameters:
      bound - the upper bound (exclusive); behavior is undefined if bound is negative
      Returns:
      the found number

    • nextFloat

      public float nextFloat()
      Description copied from class: RNG
      Gets a random float between 0.0f inclusive and 1.0f exclusive. This returns a maximum of 0.99999994 because that is the largest float value that is less than 1.0f .
      Specified by:
      nextFloat in interface IRNG
      Overrides:
      nextFloat in class RNG
      Returns:
      a float between 0f (inclusive) and 0.99999994f (inclusive)

    • nextBoolean

      public boolean nextBoolean()
      Description copied from class: RNG
      Get a random bit of state, interpreted as true or false with approximately equal likelihood. This may have better behavior than rng.next(1), depending on the RandomnessSource implementation; the default DiverRNG will behave fine, as will LightRNG and ThrustAltRNG (these all use similar algorithms), but the normally-high-quality XoRoRNG will produce very predictable output with rng.next(1) and very good output with rng.nextBoolean(). This is a known and considered flaw of Xoroshiro128+, the algorithm used by XoRoRNG, and a large number of generators have lower quality on the least-significant bit than the most- significant bit, where this method only checks the most-significant bit.
      Specified by:
      nextBoolean in interface IRNG
      Overrides:
      nextBoolean in class RNG
      Returns:
      a random boolean.

    • getRandomness

      public RandomnessSource getRandomness()
      Overrides:
      getRandomness in class RNG

    • setRandomness

      public void setRandomness​(RandomnessSource random)
      Overrides:
      setRandomness in class RNG

    • copy

      public DharmaRNG copy()
      Creates a copy of this DharmaRNG; it will generate the same random numbers, given the same calls in order, as this DharmaRNG at the point copy() is called. The copy will not share references with this DharmaRNG.
      Specified by:
      copy in interface IRNG
      Specified by:
      copy in interface RandomnessSource
      Overrides:
      copy in class RNG
      Returns:
      a copy of this DharmaRNG

    • toString

      public String toString()
      Overrides:
      toString in class RNG

    • equals

      public boolean equals​(Object o)
      Overrides:
      equals in class RNG

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class RNG

    • toSerializable

      public Serializable toSerializable()
      Returns this DharmaRNG in a way that can be deserialized even if only IRNG's methods can be called.
      Specified by:
      toSerializable in interface IRNG
      Overrides:
      toSerializable in class RNG
      Returns:
      a Serializable view of this DharmaRNG; always this