random_utils

Methods

(static) gaussian(stdev, meanopt)

Description:

  • Generate a whole random number, on a normal (Gaussian, "bell curve") distribution. For example, you might wish to create a youth gang where the members are mostly 18, but with outliers that are much younger or older. This random number generator will give more useful results than random() if you do not want the numbers to be evenly distributed.

Source:
Parameters:
Name Type Attributes Default Description
stdev Number

The amount of variance from the mean, where about 68% of the numbers will be a number +/- this amount.
mean Number <optional>
 0

The mean around which random numbers will be generated.
Returns:

a random number

(static) getAllSelectElementKeys(tree) → {Array.<String>}

Description:

  • Extracts all possible element keys from a selection tree structure.

Source:
Example
getAllSelectElementKeys(["apple", "banana", "cherry"])
=> ["apple", "banana", "cherry"]

getAllSelectElementKeys({ fruits: ["2d4:apple", "orange&pear"] })
=> ["apple", "orange", "pear"]
Parameters:
Name Type Description
tree Object | Array | string

The selection tree to extract keys from
Returns:

Array of all possible element keys that could be selected

Type
Array.<String>

(static) guid() → {String}

Description:

  • Generates a unique string (not guaranteed to be globally unique, but certainly unique in any given context).

Source:
Example
guid()
=> "6v2w2762322fwsds"
Returns:

a context unique string

Type
String

(static) nonNegativeGaussian(stdev, meanopt)

Description:

  • As the gaussian random number method, but it will not return negative numbers (without disturbing the rest of the distribution).

Source:
Parameters:
Name Type Attributes Default Description
stdev Number

The amount of variance from the mean, where about 68% of the numbers will be a number +/- this amount.
mean Number <optional>
 0

The mean around which random numbers will be generated.
Returns:

a random, non-negative number (can include zero)

(static) random(value) → {Object}

Description:

  • Return a random value from a "strategy" value, recursively. An element will be selected from an array, a function will be executed for its return value, and a string with variants will be returned with a variant selected. The value is then checked again to see if it can still be randomized further, and this process continues until a primitive value is returned (a number, object, string, or boolean).

Source:
Example
random("A")
=> "A"
random(['A','B','C']);
=> 'A'
random("{Big|Bad|Black} Dog");
=> 'Bad Dog'
random(() => ["A","B","C"]);
=> "B"
Parameters:
Name Type Description
value String | Array | function

A string with optional variants, or an array from which to select an element, or a function that returns a value.
Returns:

a single randomized instance, based on the value passed in

Type
Object

(static) randomElement(an)

Description:

  • A function that takes an array and returns a random element in the array. Does not execute functions, select a string out of string expressions, or perform any other recursive randomization.

Source:
Parameters:
Name Type Description
an collection

array
Returns:

one element of the array

(static) roll(number) → {Number}

Description:

  • Returns a random number based on a die roll string or a provided number. Math operations are supported.

Source:
Example
roll(8)
=> 4
Parameters:
Name Type Description
number Number

the maximum value to return
Returns:

a value from 1 to N

Type
Number

(static) roll(notation) → {Number}

Source:
Example
roll("3d6+2")
=> 9
roll("(2d4*10)+500")
=> 540
Parameters:
Name Type Description
notation String

a notation for a dice roll
Returns:

a die roll value

Type
Number

(static) selectElements(tree) → {Array}

Description:

  • It’s common to want to select elements according to probabalities and alternatives. Given the following format, this will return a list of the selected strings (these in turn can be whatever you are working with, such as item names, tags, etc.).

Source:
Example
{
  // the values of this object map must add up to 100%. one of the nodes
  // will be selected at random based on a 1d100 roll.
  "oneOf": {
    "A & B": 50, // returns ["A","B"] if selected
    "C": 50, // returns ["C"] if selected
  },
  // if a value is included after ":", the value will be prepended to
  // create a unique key
  "oneOf:2": { // use anything after "oneOf" to create unique key
    "A & B": 50, // returns ["A:2", "B:2"]
    B: 50, // returns ["B:2"]
  },
  // all nodes that pass 1d100 checks are added (100 = always). Each one is
  // checked against a separate 1d100 roll.
  "allOf": {
    A: 20,
    "2d3:B": 75, // if selected, add 2d3 "B" nodes
  },
  // this is 1d2 of the child nodes, which can only be an array
  "someOf:1d2": ["2d3:Cash Register"],
};
Parameters:
Name Type Description
tree Object | Array | string

The expression of a selection tree as an object, an array of nodes, or a string representing a single node
Returns:

a list of selected strings

Type
Array

(static) shuffle(array)

Description:

  • Randomly shuffle the position of the elements in an array (uses Fisher-Yates shuffle). random() is usually more efficient, but if you need to iterate through a set of values in a random order, without traversing the same element more than once, shuffle() is a better way to randomize your data.

Source:
Example
shuffle(['A','B','C'])
=> ['C','A','B']
Parameters:
Name Type Description
array Array

The array to shuffle (in place)

(static) test(percentage, value1opt, value2opt) → {Boolean|any}

Description:

  • Test against a percentage that something will occur.

Source:
Example
if (test(80)) {
    // Happens 80% of the time.
}
test(15, 'A', 'B')
=> 'B'
Parameters:
Name Type Attributes Description
percentage Number

The percentage chance that the function returns true
value1 any <optional>

the value to return if the test succeeds
value2 any <optional>

the value to return if the test fails
Returns:

true if test passes, false otherwise

Type
Boolean | any