RandomSelection

Methods

(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_selection.js, line 212

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_selection.js, line 246

Example

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

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

Parameters:

Returns:

Type

Array.<String>