oneOf.js
This module implements a tool for generating adaptive text snippets. The syntax for using oneOf is:
oneOf("foo", "bar", "baz").randomly()
oneOf(...snippets) -> Object
Takes any number of arguments (at least one) and returns an Object with the following methods. This function is the top level export of this module.
Each one of those methods returns a closure which iterates over the arguments in some particular way. Those closures also have a special property: They supply a toString()
method which is just equivalent ot call()
. In practice, what this means is that you can treat them as either functions, or as values that stringify to a text snippet according to certain rules.
This means that you can use oneOf
inline, inside strings, without parenthetising and calling it:
"#{oneOf('dog', 'cat', 'alpaca').randomly()}"
"#{(oneOf('dog', 'cat', 'alpaca').randomly())()}" # Equivalent
However, keep in mind that this will create a new object each time, so it's only useful for randomising text; otherwise, it will behave as a totally new iterator each time.
A note about initialisation
The methods that generate random text can optionally take an undum.System
object as an argument. This object is passed into your code by Undum, and it contains a random number generator set up by Undum. This allows for random text to be consistently generated across different loads of the same saved game.
For this reason, text snippets with random variations should be initialised inside a function that has access to it, unless it is intentional that they should not be consistent across saves. This means that they should be created inside your undum.game.init
function; creating them inside a situation's content
function will not work as intended, since a new closure will be created every time the situation is entered.
Object Methods
cycling() -> Function
Returns a closure that iterates over the list and returns each one in order, going back to the first one when it runs out.
stopping() -> Function
Returns a closure that iterates over the list and returns each one in order, then repeats the last item when it runs out.
randomly(system) -> Function
Optionally takes an Undum System
object as an argument. If one is provided, then random results will be consistent across saves.
Returns a closure that returns a random item of the list each time it's called. It will never return the same item twice in a row.
trulyAtRandom(system) -> Function
Optionally takes an Undum System
object as an argument. If one is provided, then random results will be consistent across saves.
Returns a closure that returns a random item of the list each time it's called. Unlike randomly()
, this can return the same item twice in a row.
inRandomOrder(system) -> Function
Optionally takes an Undum System
object as an argument. If one is provided, then random results will be consistent across saves.
Returns a closure that returns the items of the list one at a time, in a random order. When it runs out, it goes back to the beginning of that random order.