# tombola.js

Random/chance generation methods, geared towards creating procedural generation, generative art/music etc. It's a simple set of functions put together for my own use, but hopefully useful to others. Features like weighted functions, and a persistent deck which can be drawn from, can simplify the process of creating interesting outcomes.

##
**Basic Generation**

### range

`tombola.range( min, max );`

returns: integer

Randomly generates a whole number in the range from 'min' to 'max'.

### rangeFloat

`tombola.rangeFloat( min, max );`

returns: float

Randomly generates a float number in the range from 'min' to 'max'.

### dice

`tombola.dice( die, sides );`

returns: integer

Randomly generates a whole number from the total of simulated dice rolls.

### fudge

`tombola.fudge( die, strength? );`

returns: integer

Randomly generates a positive or negative modifier (or zero), based on the concept of "Fudge dice".

### fudgeFloat

`tombola.fudgeFloat( die, strength? );`

returns: float

Randomly generates a float positive or negative modifier (or zero), based on the concept of "Fudge dice".

### chance

`tombola.chance( chance, possibility );`

returns: boolean

Randomly generates a true or false based on a probability fraction, e.g a 'chance' of 1 and 'possibility' of 5 will give the function a 1 in 5 chance of returning true.

### percent

`tombola.percent( percentage );`

returns: boolean

Randomly generates a true or false based on a probability percentage. e.g a 'percentage' of 25 will give the function a 25% chance of returning true.

### item

`tombola.item( [item1, item2, etc...] );`

returns: item

Randomly picks from an array of items (can be strings, numbers, objects etc) with equal probability.

##
**Weighting**

### weightedNumber

`tombola.weightedNumber( [weight1, weight2, etc...] );`

returns: integer

Randomly generates a whole number with a weighted probability. e.g using weights of [10, 5, 5] would pick a number between 1 - 3, where 1 is twice as likely to be returned than either 2 or 3.

### weightedItem

`tombola.weightedItem( [item1, item2, etc...] , [weight1, weight2, etc...] );`

returns: item from array

Randomly picks from an array of items (can be strings, numbers, objects etc) with a weighted probability. e.g using the items ['cat', 'dog', 'tortoise'] and using weights of [10, 5, 5] would randomly return one of the pets, but 'cat' would be twice as likely to be returned than either 'dog' or 'tortoise'.

### weightedFunction

`tombola.weightedFunction( [function1, function2, etc...] , [weight1, weight2, etc...] );`

returns: executes a given function

Randomly picks from an array of functions, using a weighted probability, and executes that function. e.g using an array of functions [blur, fade, dissolve], and using weights of [10, 5, 5] would randomly call one of the given functions, but the function 'blur' would be twice as likely to be picked than either 'fade' or 'dissolve'.

##
**Clusters**

### cluster

`tombola.cluster( quantity, min, max, spread );`

returns: integer array

Randomly generates an array of whole numbers, which are clustered around a randomly selected point between 'min' and 'max'. 'spread' sets how wide the cluster is, e.g if the center of the cluster is 50, and 'spread' is set to 10, generated numbers can be anything from 40 to 60 (-10 and +10 of 50). The chance is evenly distributed.

### clusterFudge

`tombola.clusterFudge( quantity, min, max, die, strength? );`

returns: integer array

Randomly generates an array of whole numbers, which are clustered around a randomly selected point between 'min' and 'max', same as tombola.cluster(); The difference is that chance is not evenly distributed, it can be weighted so that generated numbers are more heavily distributed around the center of the cluster. Higher 'strength' and fewer 'die' will give a more even distribution, while lower 'strength' and more 'die' will make a more center-heavy cluster. 'strength' and 'die' refer to "Fudge dice" properties (see tombola.fudge();). 'strength' x 'die' = the total spread of the cluster.

##
**Persistent Deck**

### deck

`var DECK = new tombola.deck( [item1, item2, etc...] );`

Creates an instance of tombola.deck(); It's a persistant deck/hat/tombola which can contain a set of items which can be randomly drawn from, added to, looked at or shuffled. A simple example would be if you wanted a set of names to be drawn from a hat in a random order and without repetition.

### draw

`DECK.draw( index? );`

returns: item

Selects an item from the deck, either randomly or at a given index, and removes the item from the deck so that it won't be drawn again.

### look

`DECK.look( index? );`

returns: item

Selects an item from the deck, either randomly or at a given index, but leaves the item in the deck so that it may be looked at or drawn again.

### insert

`DECK.insert( item, index? );`

Adds an item to the deck, either randomly or at a given index.

### shuffle

`DECK.shuffle();`

Randomly shuffles the order of the deck contents.

### show

`DECK.show();`

returns: item array

Simply returns a list of the deck contents in their current state.