README

dice.js is a javscript dice roller and probability calculator.

Usage

Here is a small sample of supported dice roll expressions:

    d%        /* roll a percentile die */
    6#3d6     /* roll 3d6 six times (D&D abilities scores) */
    d20>=11   /* roll a d20 and check if greater or equal to target number (D&D to-hit roll) */
    4#d6>=5   /* roll four d6s and check each if 5 or 6 (Chainmail to-hit rolls) */
    max(2#d6) /* take the maximum of two d6s */
    d6 - d6   /* the difference of two d6s */

In addition to being a dice roller, dice.js also allows you to compute exact probabilities (up to JavaScript rounding errors). Quickly find the probabilities for these simple expressions:

    prob (3d6); prob(3d6>=10); stats(3d6); cdf(3d6); ~cdf(3d6); sum(prob(3d6))

Or arbitrarily complex ones, such as this expression to create a function to generate gems in accordance with the rules on page 40 of OD&D Vol. 2. Here is an implementation of Aher's theoretical method of computing exact gem probabilities from the thread Analysis of OD&D treasure types:

    gemvalue <- {"10":1,"50":2,"100":3,"500":4,"1000":5,"5000":6,"10000":7,"25000":8,"50000":9,"100000":10,"500000":11}
    gemprob <- censor(p(geom(5/6) + (pick [1 => 10%, 2 => 15%, 3 => 50%, 4 => 15%, 5 => 10%])), 1, 11)

Then you may enter

    gemprob after gemvalue         /* Generate the gem probability mass function */
    stats(gemprob after gemvalue)  /* See descriptive statistics for gems */
    10 # pick (gemprob ∘ gemvalue) /* Randomly generate 10 gems from the distribution */

TMTOWTDI:

Here are 4 ways to roll one six-sided die:

    d
    d6
    1d6
    choose[1..6]

Roll four d6, keep the highest 3 and sum. Here are two alternative ways to do it:

    4d6k3
    sum(high(3, (4#d)))

Roll two dice, find the pmf of the minimum. Two ways to do it:

    prob(min(2#d6))
    orderstat(d6, 2, 1)

Roll three d6, reroll 1s and sum. Again, two different ways to do it:

    choose[2..6]+choose[2..6]+choose[2..6]
    sum(3#choose[2..6])

Roll one die randomly chosen from the set of platonic dice. Two ways:

    d(choose [4,6,8,12,20])
    [d4, d6, d8, d12, d20] ∘ (z5)

Running the web version

Some commands only work in the REPL and do not work in the web version. These commands should be avoided in the current web version: save, load, script, noscript, dir, show.

Running the REPL

At a bash shell, enter

    node cli.js

You'll see the prompt

    In[0]  :=

Enter commands. To quit, press Ctrl+D or enter the command exit (or quit or bye or close or stop or end).

Tests

In the source code archive, there is a tests subdirectory. These tests may be run from the REPL using the load "tests/FILE" command or directly from the command-line:

    node cli.js < tests/Treasure.pal
    node cli.js < tests/sniff.pal
    node cli.js < tests/sql.pal
    node cli.js < tests/bayes.pal
    node cli.js < tests/tali.pal

Among other things, these tests provide many examples.

Warning: A few of the other tests are for outdated versions and won't run anymore.

Bugs

This code is still early alpha quality. There will be bugs. The EXAMPLES should work ok, but improper usage such as entering an ungrammatical expression will throw an error, print an error message and possibly exit you out to the command line.

Language

This code is written in pure JavaScript. It should run in a browser, from the command-line, as a chatbot plugin for chatbots like Hubot that support JavaScript, or in a server environment such as one that supports node.js.

Required software to build the project

Customizing the build scripts

In build.sh, change the JAVA and CLOSURE variables near the top to point to the location of Java and Google's closure-compiler:

JAVA=java
CLOSURE=~/bin/compiler.jar

In makepage.sh, change the MARKDOWN variable near the top to point to the location of the Markdown.pl Perl script:

MARKDOWN=~/bin/Markdown.pl

Since the markdown files use unicode, add the following pragma near the top of your Markdown.pl script:

use feature 'unicode_strings';

Building the project

At a bash shell, enter

./build.sh

Code files

Intermediate files created by the build process

Documentation

The source files are in the top directory in markdown format with .md file extensions. The HTML-ized versions are in the html/ subdirectory with .html file extensions.

Static web version

The web version lives in the html/ subdirectory. It's purpose is to run the code in a web browser, rather than running it in a console using node.js. The files in the html/ subdirectory are all built from files in the parent directory.

Other files

Goals of this software project

There are already many fine online and offline dice rollers, for example,

I started writing this software to accomplish several goals. I wanted:



AUTHORS BUGS DISCUSSION LICENSE NAME NEWS README SOURCE TODO TRY VERSION

Last update: Fri Sep 23 2016