A random number generator carried in a game's state rather than the process dictionary.
Every function here takes a generator and returns {value, next_generator}. A caller must
thread the returned generator into the following call; reusing an earlier one repeats its
values. Given the same seed and the same sequence of calls, a run replays exactly.
Wraps :rand's stateful API on the :exsss algorithm.
rng = Cauldron2D.Rng.new(1234)
{damage, rng} = Cauldron2D.Rng.dice(rng, 2, 6)
{critical?, _rng} = Cauldron2D.Rng.chance(rng, 1, 20)Summary
Functions
An integer in lo..hi, inclusive, uniformly. hi must not be less than lo.
True with probability numerator / denominator. Both must be positive integers.
The sum of count independent rolls of a die with sides faces.
A generator seeded from seed, which may be any integer.
One element of list, each equally likely, or nil when list is empty.
A generator seeded from the system clock, and the seed it used.
An integer in 1..n, uniformly. n must be at least 1.
The elements of list in a random order.
One value from a list of {weight, value} pairs, chosen in proportion to the weights.
Types
@type t() :: :rand.state()
Functions
An integer in lo..hi, inclusive, uniformly. hi must not be less than lo.
@spec chance(t(), pos_integer(), pos_integer()) :: {boolean(), t()}
True with probability numerator / denominator. Both must be positive integers.
@spec dice(t(), pos_integer(), pos_integer()) :: {pos_integer(), t()}
The sum of count independent rolls of a die with sides faces.
A generator seeded from seed, which may be any integer.
One element of list, each equally likely, or nil when list is empty.
A generator seeded from the system clock, and the seed it used.
Keep the returned seed to replay the same run through new/1.
@spec roll(t(), pos_integer()) :: {pos_integer(), t()}
An integer in 1..n, uniformly. n must be at least 1.
The elements of list in a random order.
A Fisher-Yates shuffle, so every ordering is equally likely however long the list is. Costs one roll per element.
@spec weighted(t(), [{non_neg_integer(), term()}]) :: {term() | nil, t()}
One value from a list of {weight, value} pairs, chosen in proportion to the weights.
Weights are relative and need not sum to anything in particular. Each must be a non-negative
integer, and at least one must be positive; a weight of 0 is a value that is never chosen.
Returns nil for an empty list.
Raises ArgumentError on a weight that is not a non-negative integer, and on a list whose
weights are all zero — a list that cannot answer, rather than one that answers oddly.