dice-notation-js

    1.0.3 • Public • Published

    Dice Notation

    Build Status Coverage Status NPM

    Parses dice notation and rolls dice.

    Install

    Browser

    You can grab a hosted version here:

    <script src="https://cdn.jsdelivr.net/gh/chapelr/dice-notation@latest/dist/dice.min.js" type="text/javascript"></script>
    

    Or include dist/dice.min.js or dice.js as appropriate in your webpage.

    This will expose the global Dice API, or create a UMD module, if appropriate.

    NPM

    npm install dice-notation-js
    

    Then require or import it:

    const Dice = require('dice-notation-js');
    

    Usage

    Exposes three functions, Dice(), Dice.detailed() and Dice.parse().

    Dice()

    Syntax:

    • Dice(notation [, randomFunction])
    • Dice(number, type [, randomFunction])

    Takes a string of dice notation, or two numbers representing the number and type of dice to roll, and optionally a randomization function (that replaces Math.random()) and returns the result of the dice roll.

    Arguments:

    • notation (string): You can pass the funciton a string of dice notation, e.g., 3d6+2, or 1d20.
    • number (number): You can pass the function a number of dice to roll and the number of sides each die should have. This argument is the number of dice to roll.
    • type (number): You can pass the function a number of dice to roll and the number of sides each die should have. This argument is the number of sides each die should have.
    • randomFunction (function) optional: You may pass a function that returns a random number between 0 and 1 that will be used in place of Math.random(), such as to use a seedable PRNG.

    Examples

    Basic use:

    // All of the following are functionally the same:
    
    Dice('3d6+2');
    Dice('3d6') + 2;
    Dice(3, 6) + 2;

    Using a seedable PRNG, such as seedrandom:

    const Dice = require('dice-notation-js');
    const prng = require('seedrandom')('hello');
    
    Dice('3d6+2', prng);
    Dice('3d6', prng) + 2;
    Dice(3, 6, prng) + 2;

    Dice.detailed()

    Syntax:

    • Dice.detailed(notation [, randomFunction])
    • Dice.detailed(number, type [, randomFunction])

    Takes a string of dice notation, rolls it like Dice(), but returns additional details for your use.

    Arguments:

    • notation (string): You can pass the funciton a string of dice notation, e.g., 3d6+2, or 1d20.
    • number (number): You can pass the function a number of dice to roll and the number of sides each die should have. This argument is the number of dice to roll.
    • type (number): You can pass the function a number of dice to roll and the number of sides each die should have. This argument is the number of sides each die should have.
    • randomFunction (function) optional: You may pass a function that returns a random number between 0 and 1 that will be used in place of Math.random(), such as to use a seedable PRNG.

    Examples

    var roll = Dice.detailed('3d6+10');
    
    console.log(roll); 
    // -> { number: 3, type: 6, modifier: 10, rolls: [ 2, 1, 6 ], result: 19 } 

    Dice.parse()

    Syntax: Dice.parse(notation)

    Takes a string of dice notation and returns an object parsed from it. For example, the notation 6d4-1 returns the following object:

    {
        number : 6,
        type : 4,
        modifier -1
    }

    Arguments:

    • notation (string): You can pass the funciton a string of dice notation, e.g., 3d6+2, or 1d20.

    Examples

    Basic use:

    Dice.parse('1d10') // -> { number : 1, type : 10, modifier :  0 }
    Dice.parse('3d6+2') // -> { number : 3, type : 6, modifier :  2 }
    Dice.parse('2d4-1') // -> { number : 2, type : 4, modifier : -1 }

    Install

    npm i dice-notation-js

    DownloadsWeekly Downloads

    11

    Version

    1.0.3

    License

    MIT

    Unpacked Size

    9.12 kB

    Total Files

    4

    Last publish

    Collaborators

    • chapelr