rollkit
v2.1.2
Published
rollkit
Downloads
28
Readme
RollKit 2.1.2
BREAKING CHANGES
- Module Functions Symbols have been renamed using Pascal case
- Draw Function parameters have been changed to take an options object parameter instead of individual parameters
What is RollKit?
This is designed to be an all-in-one RNG utility for use in node applications. Random Numbers are generated using Random.js
Current Features
- Gambling: config, Flip, Bet
- Dice: Roll, RollSingle
- Draw: FromArray, FromDelimitedString
- Misc:
- Cards: Deck, ShuffledDeck
- String: GenRandomString
- Generate: RandomCauseOfDeath, AskMagic8Ball
- Security: MD5, SHA256, SHA512, SaltHashPassword, SaltHashPassword256
- Simple: Random Number Generator
Features will continue to be added/updated over time.
Custom Classes
Stack: Array Extension
- Added Functions
- Shuffle - returns a shuffled copy of the Stack
- Empty - removes all items from the stack
- DrawRandom - draws [x] random items from the stack
- DrawFromTop - draws [x] items from the stack sequentially from the top
- Path: src/classes/cards/stack
- Added Functions
Deck: Stack Extension
- JS Generated Card Deck
- Added Functions
- Reset - clears and regenerates a new Deck
Card: Custom Class
- Properties
- Rank [string]
- Suit [object]
- Values [array]
- Functions
- ToString - concatenates the properties into a string to be displayed
- ToCompactString - concatenates the properties into a compact, abbreviated string
- Properties
Using Function Groups
RollKit consists of 7 function groups that perform different random selection tasks.
When using es6 style imports, these groups can be imported individually.
import {Draw, Dice, Gamble} from 'rollkit'
Function Groups
Gamble
Gamble.Flip ||
---------:|---------
details | flip a coin, calling the side and wager an amount on the result
returns | result object: {side, winnings}
syntax | Gamble.Flip(['heads'/'tails'], [wager]);
example | let result = Gamble.Flip('tails', 10);
Gamble.Bet ||
--------:|---------
details | wager an amount against the house
returns | result object: {user, house, winnings}
syntax | Gamble.Bet([wager]);
example | let result = Gamble.Bet(100);
Gamble.config
Configure Gambling Calculations property | details --------:|--------- Flip.winningsPercentage | percentage of wager to use in winnings calculation Bet.winningsPercentage | percentage of wager to use in winnings calculation
Draw
Draw Global Options || --------------:|---------------- count | number of items to draw allowduplicates | allow an item to be drawn more than once shuffle | shuffle the array prior to drawing drawfromtop | draw each item from the top of the array (ignored if weighted)
Draw.FromArray ||
----------:|----------
details | draw one or more items at random from an array
returns | array of winning items |
syntax | Draw.FromArray([array], {[count], [shuffle], [drawfromtop], [allowduplicates]});
example | let winners = Draw.FromArray([obj1, obj2, obj3, obj4], {count: 2, allowduplicates: false});
NOTE objects in the array passed to this function must include a numeric property that is used for weight.
if you have an array of objects without a property to be used as weight, you should create a function that iterates through the array, creating a new object from each that includes the weighted property.
For example the array ['string1', 'string2', 'string3', 'string4']
should be converted to [{string: 'string1', [name of weight property]: [weight]}, {string: 'string2', [name of weight property]: [weight]}]
Example [{string: 'string1', weight: 1}, {string: 'string2', weight: 2}] etc..
Draw.FromDelimitedString ||
----------:|----------
details | draw one or more items at random from a delimited string of items
returns | delimited string of winning items
syntax | Draw.FromDelimitedString( [del_string], {[delimiter], [count], [shuffle], [drawfromtop], [allowduplicates]} );
example | let winners = Draw.FromDelimitedString('billy,bobby,suzie,sally', {delimiter: ',', count: 2, allowduplicates: true);
count and allowduplicates are optional parameters. if omitted, count defaults to 1 and allowduplicates to false;
Generate
Generate.RandomCauseOfDeath ||
---------:|----------
details | generates a random cause of death
returns | String
syntax | Generate.RandomCauseOfDeath()
Generate.AskMagic8Ball ||
---------:|----------
details | generates an 8-ball response to a question
returns | String
syntax | Generate.AskMagic8Ball()
Misc
Misc.Cards
Misc.Cards.Deck ||
---------:|----------
details | generate a deck of cards
returns | Deck: {[game], [items]}
syntax | Misc.Cards.Deck([*game]);
example | let deck = Misc.Cards.Deck();
parameter | game (optional)
param info | specify a game to determine the value of certain cards
Misc.Cards.ShuffledDeck ||
---------:|----------
details | generate a shuffled deck of cards
returns | Deck: {[game], [items]]}
syntax | Misc.Cards.ShuffledDeck([*game]);
example | let deck = Misc.Cards.ShuffledDeck();
parameter | game (optional)
param info | specify a game to determine the value of certain cards
Card ||
details | Card Object
property | rank: string
property | suit: object {name, symbol}
property | value: array of possible values
property | faceUp: bool
method | ToCompactString
method | ToString
method | Flip: changes to value of faceUp
Stack || ---------:|---------- details | extends Array method | ShuffleItems: returns a shuffled copy of the current Array method | DrawFromTop: returns Array of Cards from the top of the Stack. These Cards are removed from the source Stack method | DrawRandom: returns Array of random Cards from the Stack. These Cards are removed from the source Stack method | Empty: clears the Stack of all Cards
Deck || ---------:|---------- details | extends Stack method | ShuffleDeck: returns a shuffled copy of the current Deck method | Empty: clears the current Deck of all Cards method | Reset: resets the current Deck to a full, unshuffled Deck
Example Deck
{
"game":"blackjack",
"items": [
{"rank":"Ace","suit":{"name":"Hearts","symbol":"♥"},"value":[1,11],"faceUp":false},
{"rank":"2","suit":{"name":"Hearts","symbol":"♥"},"value":[2],"faceUp":false},
{"rank":"3","suit":{"name":"Hearts","symbol":"♥"},"value":[3],"faceUp":false},
{"rank":"4","suit":{"name":"Hearts","symbol":"♥"},"value":[4],"faceUp":false},
{"rank":"5","suit":{"name":"Hearts","symbol":"♥"},"value":[5],"faceUp":false},
{"rank":"6","suit":{"name":"Hearts","symbol":"♥"},"value":[6],"faceUp":false},
{"rank":"7","suit":{"name":"Hearts","symbol":"♥"},"value":[7],"faceUp":false},
{"rank":"8","suit":{"name":"Hearts","symbol":"♥"}, "value":[8],"faceUp":false},
{"rank":"9","suit":{"name":"Hearts","symbol":"♥"}, "value":[9],"faceUp":false},
{"rank":"10","suit":{"name":"Hearts","symbol":"♥"}, "value":[10],"faceUp":false},
{"rank":"Jack","suit":{"name":"Hearts","symbol":"♥"}, "value":[10],"faceUp":false},
{"rank":"Queen","suit":{"name":"Hearts","symbol":"♥"}, "value":[10],"faceUp":false},
{"rank":"King","suit":{"name":"Hearts","symbol":"♥"}, "value":[10],"faceUp":false},
{"rank":"Ace","suit":{"name":"Spades","symbol":"♠"}, "value":[1,11],"faceUp":false},
{"rank":"2","suit":{"name":"Spades","symbol":"♠"}, "value":[2],"faceUp":false},
{"rank":"3","suit":{"name":"Spades","symbol":"♠"}, "value":[3],"faceUp":false},
{"rank":"4","suit":{"name":"Spades","symbol":"♠"}, "value":[4],"faceUp":false},
{"rank":"5","suit":{"name":"Spades","symbol":"♠"}, "value":[5],"faceUp":false},
{"rank":"6","suit":{"name":"Spades","symbol":"♠"}, "value":[6],"faceUp":false},
{"rank":"7","suit":{"name":"Spades","symbol":"♠"}, "value":[7],"faceUp":false},
{"rank":"8","suit":{"name":"Spades","symbol":"♠"}, "value":[8],"faceUp":false},
{"rank":"9","suit":{"name":"Spades","symbol":"♠"}, "value":[9],"faceUp":false},
{"rank":"10","suit":{"name":"Spades","symbol":"♠"}, "value":[10],"faceUp":false},
{"rank":"Jack","suit":{"name":"Spades","symbol":"♠"}, "value":[10],"faceUp":false},
{"rank":"Queen","suit":{"name":"Spades","symbol":"♠"}, "value":[10],"faceUp":false},
{"rank":"King","suit":{"name":"Spades","symbol":"♠"}, "value":[10],"faceUp":false},
{"rank":"Ace","suit":{"name":"Clubs","symbol":"♣"}, "value":[1,11],"faceUp":false},
{"rank":"2","suit":{"name":"Clubs","symbol":"♣"}, "value":[2],"faceUp":false},
{"rank":"3","suit":{"name":"Clubs","symbol":"♣"}, "value":[3],"faceUp":false},
{"rank":"4","suit":{"name":"Clubs","symbol":"♣"}, "value":[4],"faceUp":false},
{"rank":"5","suit":{"name":"Clubs","symbol":"♣"}, "value":[5],"faceUp":false},
{"rank":"6","suit":{"name":"Clubs","symbol":"♣"}, "value":[6],"faceUp":false},
{"rank":"7","suit":{"name":"Clubs","symbol":"♣"}, "value":[7],"faceUp":false},
{"rank":"8","suit":{"name":"Clubs","symbol":"♣"}, "value":[8],"faceUp":false},
{"rank":"9","suit":{"name":"Clubs","symbol":"♣"}, "value":[9],"faceUp":false},
{"rank":"10","suit":{"name":"Clubs","symbol":"♣"}, "value":[10],"faceUp":false},
{"rank":"Jack","suit":{"name":"Clubs","symbol":"♣"}, "value":[10],"faceUp":false},
{"rank":"Queen","suit":{"name":"Clubs","symbol":"♣"}, "value":[10],"faceUp":false},
{"rank":"King","suit":{"name":"Clubs","symbol":"♣"}, "value":[10],"faceUp":false},
{"rank":"Ace","suit":{"name":"Diamonds","symbol":"♦"}, "value":[1,11],"faceUp":false},
{"rank":"2","suit":{"name":"Diamonds","symbol":"♦"}, "value":[2],"faceUp":false},
{"rank":"3","suit":{"name":"Diamonds","symbol":"♦"}, "value":[3],"faceUp":false},
{"rank":"4","suit":{"name":"Diamonds","symbol":"♦"}, "value":[4],"faceUp":false},
{"rank":"5","suit":{"name":"Diamonds","symbol":"♦"}, "value":[5],"faceUp":false},
{"rank":"6","suit":{"name":"Diamonds","symbol":"♦"}, "value":[6],"faceUp":false},
{"rank":"7","suit":{"name":"Diamonds","symbol":"♦"}, "value":[7],"faceUp":false},
{"rank":"8","suit":{"name":"Diamonds","symbol":"♦"}, "value":[8],"faceUp":false},
{"rank":"9","suit":{"name":"Diamonds","symbol":"♦"}, "value":[9],"faceUp":false},
{"rank":"10","suit":{"name":"Diamonds","symbol":"♦"}, "value":[10],"faceUp":false},
{"rank":"Jack","suit":{"name":"Diamonds","symbol":"♦"}, "value":[10],"faceUp":false},
{"rank":"Queen","suit":{"name":"Diamonds","symbol":"♦"}, "value":[10],"faceUp":false},
{"rank":"King","suit":{"name":"Diamonds","symbol":"♦"}, "value":[10],"faceUp":false}
]
}game tells Misc.Cards how to set the values of each card in a deck.
For example, Misc.Cards.Deck('blackjack') returns a deck where Aces are worth 1 or 11, and Jack,Queen,King are worth 10
Dice
Dice.Roll ||
----------:|----------
details | roll X number of Y-sided dice with an optional modifier
returns | result object: {[roll values], sum}
syntax | Dice.Roll([die count]d[sides][+modifier]);
example | let roll = Dice.Roll('1d20+3');
modifier is an optional parameter
String
String.GenRandomString ||
----------:|----------
details | generate a random string of the specified length
returns | string
syntax | String.GenRandomString([length])
example | let rs = String.GenRandomString(16)
Security
Security.MD5 ||
----------:|----------
details | hash a string using salt
returns | result object: {salt, stringHash}
syntax | Security.MD5([string], [salt])
example | let md5 = Security.MD5('plain text', 'random_salt')
Security.SHA256 ||
----------:|----------
details | hash a string using salt
returns | result object: {salt, stringHash}
syntax | Security.SHA256([string], [salt])
example | let sha = Security.SHA256('plain text', 'random_salt')
Security.SHA512 ||
----------:|----------
details | hash a string using salt
returns | result object: {salt, stringHash}
syntax | Security.SHA512([string], [salt])
example | let sha = Security.SHA512('plain text', 'random_salt')
*can be used with String.GenRandomString: Security.SHA512('plain text', String.GenRandomString(16))
Security.SaltHashPassword ||
----------:|----------
details | hash a password using a generated salt
returns | result object: {salt, passwordHash}
syntax | Security.SaltHashPassword([password])
example | let result = Security.SaltHashPassword('mypassword')
Security.SaltHashPassword256 ||
----------:|----------
details | hash a password using a generated salt
returns | result object: {salt, passwordHash}
syntax | Security.SaltHashPassword256([password])
example | let result = Security.SaltHashPassword256('mypassword')
Simple
Simple ||
-----:|-----
details | generate a random number between 1 and max
returns | integer
syntax | Simple([max]);
example | let num = Simple(30);
Usage
node.js
In your project, run the following command:
npm install rollkit
Add RollKit in your code:
var rollkit = require('rollkit');
License
ISC License (ISC)