Package squidpony.squidmath

Class CriticalRNG

java.lang.Object
squidpony.squidmath.RNG
squidpony.squidmath.CriticalRNG
All Implemented Interfaces:
Serializable, IRNG, RandomnessSource
public class CriticalRNG
extends RNG
A type of RNG that can generate values larger or smaller than the normal maximum or minimum, based on a modifier. You should not use this as a general-purpose substitute for RNG; it is meant for cases where there is no hard maximum or minimum for a random value, so it is a poor fit for getting random items from collections or shuffling. It also uses a curved distribution (almost Gaussian, but slightly more shallow), which makes its results to be most often near the center of the range they can fall into. The luck field affects the distribution simply, and should generally be between -0.5f and 0.5f except in cases where a character or event routinely defies all odds. There is no value for luck that will prevent this from sometimes producing values outside the requested range, though at luck = 0 it is somewhat rare for the bounds to be significantly exceeded.
The name comes from "critical hit," the rare but potentially very significant strike in many role-playing games.
Created by Tommy Ettinger on 9/20/2017.
See Also:
Serialized Form

  • Field Details

    • luck

      public float luck
      Positive for higher results, negative for lower results; usually this is small, between -0.5f and 0.5f .

  • Constructor Details

    • CriticalRNG

      public CriticalRNG()
      Makes a CriticalRNG with a luck factor of 0 and a randomly-seeded DiverRNG for its RandomnessSource.

    • CriticalRNG

      public CriticalRNG​(long seed)
      Makes a CriticalRNG with a luck factor of 0 and a DiverRNG with the given seed for its RandomnessSource.
      Parameters:
      seed - any long

    • CriticalRNG

      public CriticalRNG​(CharSequence seedString)
      Makes a CriticalRNG with a luck factor of 0 and a DiverRNG with the given seed for its RandomnessSource (this will hash seedString using CrossHash.hash64(CharSequence) and use the result to seed the DiverRNG).
      Parameters:
      seedString - any String

    • CriticalRNG

      public CriticalRNG​(RandomnessSource random)
      Makes a CriticalRNG with a luck factor of 0 and the given RandomnessSource.
      Parameters:
      random - a RandomnessSource, such as a LongPeriodRNG or LightRNG

    • CriticalRNG

      public CriticalRNG​(float luck)
      Makes a CriticalRNG with the given luck factor and a randomly-seeded DiverRNG for its RandomnessSource.
      Parameters:
      luck - typically a small float, often between -0.5f and 0.5f, that will affect the results this returns

    • CriticalRNG

      public CriticalRNG​(long seed, float luck)
      Makes a CriticalRNG with the given luck factor and a DiverRNG with the given seed for its RandomnessSource.
      Parameters:
      seed - any long
      luck - typically a small float, often between -0.5f and 0.5f, that will affect the results this returns

    • CriticalRNG

      public CriticalRNG​(CharSequence seedString, float luck)
      Makes a CriticalRNG with a luck factor of 0 and a DiverRNG with the given seed for its RandomnessSource (this will hash seedString using CrossHash.hash64(CharSequence) and use the result to seed the DiverRNG).
      Parameters:
      seedString - any String
      luck - typically a small float, often between -0.5f and 0.5f, that will affect the results this returns

    • CriticalRNG

      public CriticalRNG​(RandomnessSource random, float luck)
      Makes a CriticalRNG with a luck factor of 0 and the given RandomnessSource.
      Parameters:
      random - a RandomnessSource, such as a LongPeriodRNG or LightRNG
      luck - typically a small float, often between -0.5f and 0.5f, that will affect the results this returns

  • Method Details

    • nextDouble

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

    • nextDouble

      public double nextDouble​(double max)
      Description copied from class: RNG
      This returns a random double between 0.0 (inclusive) and outer (exclusive). The value for outer can be positive or negative. Because of how math on doubles works, there are at most 2 to the 53 values this can return for any given outer bound, and very large values for outer will not necessarily produce all numbers you might expect.
      Specified by:
      nextDouble in interface IRNG
      Overrides:
      nextDouble in class RNG
      Parameters:
      max - the outer exclusive bound as a double; can be negative or positive
      Returns:
      a double between 0.0 (inclusive) and outer (exclusive)

    • 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.

    • nextLong

      public long nextLong()
      Description copied from class: RNG
      Get a random long between Long.MIN_VALUE to Long.MAX_VALUE (both inclusive).
      Specified by:
      nextLong in interface IRNG
      Specified by:
      nextLong in interface RandomnessSource
      Overrides:
      nextLong in class RNG
      Returns:
      a 64-bit random long.

    • nextLong

      public long nextLong​(long bound)
      Description copied from class: RNG
      Gets a pseudo-random long between 0 and bound. Exclusive on bound (which must be positive), with an inner bound of 0 If bound is negative or 0, this always returns 0. You can use RNG.nextSignedLong(long) to use a negative bound. The technique that
      Credit for this method goes to Rafael Baptista's blog for the original idea, and the JDK10 Math class' usage of Karatsuba multiplication for the current algorithm. This method is drastically faster than the previous implementation when the bound varies often (roughly 4x faster, possibly more). It also always gets exactly one random long, so by default it advances the state as much as RNG.nextLong().
      Specified by:
      nextLong in interface IRNG
      Overrides:
      nextLong in class RNG
      Parameters:
      bound - the outer exclusive bound; should be positive, otherwise this always returns 0L
      Returns:
      a random long between 0 (inclusive) and bound (exclusive)

    • nextInt

      public int nextInt​(int bound)
      Description copied from class: RNG
      Returns a random non-negative integer below the given bound, or 0 if the bound is 0 or negative. Always makes one call to the RandomnessSource.next(int) method of the RandomnessSource that would be returned by RNG.getRandomness(), even if bound is 0 or negative, to avoid branching and also to ensure consistent advancement rates for the RandomnessSource (this can be important if you use a SkippingRandomness and want to go back before a result was produced).
      This method changed a fair amount on April 5, 2018 to better support RandomnessSource implementations with a slower nextLong() method, such as Lathe32RNG, and to avoid branching/irregular state advancement/modulus operations. It is now almost identical to RNG.nextIntHasty(int), but won't return negative results if bound is negative (matching its previous behavior). This may have statistical issues (small ones) if bound is very large (the estimate is still at least a bound of a billion or more before issues are observable). Consider RNG.nextSignedInt(int) if the bound should be allowed to be negative; RNG.nextIntHasty(int) is here for compatibility with earlier versions, but the two methods are very similar.
      Credit goes to Daniel Lemire, http://lemire.me/blog/2016/06/27/a-fast-alternative-to-the-modulo-reduction/
      Specified by:
      nextInt in interface IRNG
      Overrides:
      nextInt in class RNG
      Parameters:
      bound - the upper bound (exclusive)
      Returns:
      the found number

    • nextIntHasty

      public int nextIntHasty​(int bound)
      Description copied from class: RNG
      Returns a random non-negative integer between 0 (inclusive) and the given bound (exclusive), or 0 if the bound is 0. The bound can be negative, which will produce 0 or a negative result. Uses an aggressively optimized technique that has some bias, but mostly for values of bound over 1 billion. This method is no more "hasty" than RNG.nextInt(int), but it is a little faster than that method because this avoids special behavior for when bound is negative.
      Credit goes to Daniel Lemire, http://lemire.me/blog/2016/06/27/a-fast-alternative-to-the-modulo-reduction/
      Overrides:
      nextIntHasty in class RNG
      Parameters:
      bound - the outer bound (exclusive), can be negative or positive
      Returns:
      the found number

    • nextInt

      public int nextInt()
      Description copied from class: RNG
      Get a random integer between Integer.MIN_VALUE to Integer.MAX_VALUE (both inclusive).
      Specified by:
      nextInt in interface IRNG
      Overrides:
      nextInt in class RNG
      Returns:
      a 32-bit random int.

    • getRandomElement

      public <T> T getRandomElement​(T[] array)
      Description copied from class: RNG
      Returns a random element from the provided array and maintains object type.
      Specified by:
      getRandomElement in interface IRNG
      Overrides:
      getRandomElement in class RNG
      Type Parameters:
      T - the type of the returned object
      Parameters:
      array - the array to get an element from
      Returns:
      the randomly selected element

    • getRandomElement

      public <T> T getRandomElement​(List<T> list)
      Description copied from class: RNG
      Returns a random element from the provided list. If the list is empty then null is returned.
      Specified by:
      getRandomElement in interface IRNG
      Overrides:
      getRandomElement in class RNG
      Type Parameters:
      T - the type of the returned object
      Parameters:
      list - the list to get an element from
      Returns:
      the randomly selected element

    • getRandomElement

      public <T> T getRandomElement​(Collection<T> coll)
      Description copied from class: RNG
      Returns a random element from the provided Collection, which should have predictable iteration order if you want predictable behavior for identical RNG seeds, though it will get a random element just fine for any Collection (just not predictably in all cases). If you give this a Set, it should be a LinkedHashSet or some form of sorted Set like TreeSet if you want predictable results. Any List or Queue should be fine. Map does not implement Collection, thank you very much Java library designers, so you can't actually pass a Map to this, though you can pass the keys or values. If coll is empty, returns null.

      Requires iterating through a random amount of coll's elements, so performance depends on the size of coll but is likely to be decent, as long as iteration isn't unusually slow. This replaces getRandomElement(Queue), since Queue implements Collection and the older Queue-using implementation was probably less efficient.

      Specified by:
      getRandomElement in interface IRNG
      Overrides:
      getRandomElement in class RNG
      Type Parameters:
      T - the type of the returned object
      Parameters:
      coll - the Collection to get an element from; remember, Map does not implement Collection
      Returns:
      the randomly selected element