GNOLL

An easy to integrate dice notation library for multiple programming languages. Use for instant support of common syntax and a library that can scale with your demands, rather than a sticky taped monstrousity of regular expressions and tears.

Here's an example of how you might use GNOLL:

**Grindon The Brave**: I want to steal from the goblin sitting at the bar.
**Dungeon Master**: Okay, give me a stealth check!
**Grindon The Brave**: Okay, that's a <1d20+5>
[GNOLL]: 21
**Dungeon Master**: Hurrah! You successfully pickpocket the goblin! However, all he had in there were some crummy dice...

You can follow Grindon's full adventure through the world of dice notation in our Documentation.

Many of our notation design decisions are explained in the documentation and compared to other dice notation parsers.

Play around

Try out our web demo! ✨

Current Status

🧑‍💻 Language Support

GNOLL was written to be the definitive solution to dice notation. The core has been written in C, but fear not! You can use GNOLL in many other programming languages too. Here are some we have examples for:

Primarily tested on Linux (Ubuntu), but functional in various forms on Windows (10, WSL) and Mac.

🎲 Dice Notation

XdY notation
Arithmetic
Fate Dice
Miscellaneous Symbolic Dice
Shorthands & Macros
Alternate Syntax
Explosions
Drop/Keep
Rerolling
Filtering
Functions

There's so many different things, we'd bore you to list them all here. For the specific details of supported notation, check out our documentation.

Getting Started

Usage from a package manager

Python

pip3 install GNOLL

Then, in your code:

from gnoll import roll
roll("1d20")
>> (0, [[12]], None)
# (return code, final result, dice breakdown (if enabled))

Or, use the command-line interface (see --help):

$ python3 -m gnoll 2d4
6
$ function gnoll() { python3 -m gnoll --breakdown "$@" ; }
$ gnoll 3d6 + 10
[5, 5, 4] --> 24

🛠️ Installing From Source

Basic Requirements

sudo apt-get install bison flex make python3-pip -y
pip install -r reqs/requirements.txt
make all

To verify your setup, try our tests:

make test

Or, just try some commands yourself!

$ ./build/dice 1d20
20

If you would like to run the 'dice' command from anywhere, use make install to add the executable to your path.

(Note that not all commands may not be able to be used this way as some symbols are reserved for use by different terminal interfaces (e.g. bash uses ! and #))

For languages other than Python/C/C++ call the corresponding make target after the commands above.