random_utils

Methods

(static) gaussian(stdev, meanopt, negativeopt)

Description:

• Generate a whole random number, on a normal (Gaussian, "bell curve") distribution. This random number generator will give more useful results than random() if you do not want the numbers to be evenly distributed.

Source:

• random_utils.js, line 171

Parameters:

Returns:

(static) guid() → {String}

Description:

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

Source:

• random_utils.js, line 31

Example

guid()
=> "6v2w2762322fwsds"

Returns:

Type

String

(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:

• random_utils.js, line 132

Example

random("A")
=> "A"
random(['A','B','C']);
=> 'A'
random("{Big|Bad|Black} Dog");
=> 'Bad Dog'
random(() => ["A","B","C"]);
=> "B"

Parameters:

Returns:

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:

• random_utils.js, line 153

Parameters:

Returns:

(static) roll(number) → {Number}

Description:

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

Source:

• random_utils.js, line 56

Example

roll(8)
=> 4

Parameters:

Returns:

Type

Number

(static) roll(notation) → {Number}

Source:

• random_utils.js, line 56

Example

roll("3d6+2")
=> 9
roll("(2d4*10)+500")
=> 540

Parameters:

Returns:

Type

Number

(static) selectElements()

Description:

• This method takes a JSON description of how to select elements in a pseudo- random fashion. It returns an array of selected tokens.

  tokens. A token may consist of the string to be returned, plus a cardinality, in the form "[cardinality]:[string]". The cardinality can be a number ("4") or a dice notation ("2d6"). This is how many times the token will appear in the output array, if it is selected. This happens any time we say the token is “added” to the array below.

  rules. There are three: some, any, and all. If an object is passed to the method, these are the property names of the object. In order to repeat rules in this object, they can be postfixed with any value such as all-1” and “all-2”. Since each rule is a property, it is associated to a property value descrining the way to select elements from that value:

  • some selects some of the tokens from the array or object. The exact number is indicated by the rule, for example “some:2d3" or “some:2”. If it’s an array, tokens are randomly selected. If it's an object, the weighted selection is based on the object as described below. Percentages must add up to 100%.

  • one synonymous with “some:1”

  • any selects any of the tokens that match against a percentage test from an array or object. If it’s an array, this is functionally equivalent to “some:1”. If it’s an object, the items are tested in order against a random percentage and those that match are added to the output array. If the table uses rarity values, these are tested in order, a similar fashion, and added to the array. Percentages do not have to add up to 100%.

  • all add all tokens from an array to the output stream. If an object is associated to the rule, all the values are added and percentage chance or rarity are ignored.

  Object tables. The keys of the object are tokens and the values are percentage values (of type number) or rarity values ("C", "U", "R"). The rule will select tokens from the object keys based on the values of the object (in effect this object forms a weighted table similar to the Table and RarityTable classes).

Source:

• random_utils.js, line 351

Example

"3:Stall"
=> ["Stall", "Stall", "Stall"]

[ "A", "2:B", "1d3:C" ]
=> ["A", "B", "B", "C"]
=> ["A", "B", "B", "C", "C", "C"]

// "&" can be used to group tokens
{ "some:1": { "A & B": 50, "C": 50 } }
=> ["A", "B"]
=> ["C"]

// same result; the postfix allows properties under the same key
{ "some-2:1": { "D": 50, "E": 50 } }
=> ["E"]

{ "some:1": ["A", "B"] }
=> ["B"]

{ "some:1": [ "A", "2:B", "1d3:C" ] }
=> ["A"]
=> ["B", "B"]
=> ["C", "C", "C"]

// 1d2 elements, each added by percentage weight. must add up to 100%
{ "some:1d2": { "A": 20, "B": 20, "C": 60 } }
=> ["A"]
=> ["C", "B"]
=> ["C", "C"]

// common, uncommon, and rare
{ "some:1": { "A": "C", "B": "U", "C": "R"} }
=> ["A"]

{ "some:1d2": { "A": "C", "B": "U" } }
=> ["A"]
=> ["B", "A"]
=> ["B", "B"]

// all does *not* have to add up to 100%
{ "all": { "A": 20, "2d3:B": 75 } }
=> []
=> ["A"]
=> ["A", "B", "B"]
=> ["B", "B", "B", "B", "B", "B"]

// four times
{ "all": ["4:A"] }
=> ["A", "A", "A", "A"]

{ "all": ["1d3:D", "1d3:E", "1d3:F"] }
=> ["D","D","D","E","F","F","F"]

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

Description:

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

Source:

• random_utils.js, line 398

Example

selectElementsKeys(["apple", "banana", "cherry"])
=> ["apple", "banana", "cherry"]

selectElementsKeys({ fruits: ["2d4:apple", "orange&pear"] })
=> ["apple", "orange", "pear"]

Parameters:

Returns:

Type

Array.<String>

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

Description:

• Test against a percentage that something will occur.

Source:

• random_utils.js, line 96

Example

if (test(80)) {
    // Happens 80% of the time.
}
test(15, 'A', 'B')
=> 'B'

Parameters:

Returns:

Type

Boolean | any