Skip to content
A simple dice roller in Crystal and libui
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.

Dice Roller

This is a simple dice roller written as an exercise to learn Crystal. It uses for the GUI. I've also written a second version of the GUI with hedron.


Assuming you have crystal installed, simply "git clone" it:

git clone

Then enter the directory and shards build

You'll find two executables under the bin/ folder: roll and rollHedron. First one uses directly, second one uses hedron.


Usage is simple. You just invoke it with


which will load the interface. You can write the roll descriptor on the text field and press the Roll! button to get the results.

Roll descriptors are of the form:

expression [expression]*


expression := dice[<+|->dice]*
dice := <number>[<a|d><number>]


1d6 : Roll 1 die of 6 sides
4d4+3 : Roll 4 dice of 4 sides each, sum the results, and add 3 to that 
1a8 3d10: Roll 1 die of 8 sides, with explosions, then 3 dice of 10 sides, add these results, and show both rolls individually

explosions mean that, if the result is the maximum value for the die, it gets rolled again and the totals are added. Ex., a 6 on a 6-sided die means a new roll, which yields let's say a 3, result is 6+3=9.


The Dice Roller uses a config file, called config.ini, and stored in the {XDG_CONFIG_HOME}/roll directory.

This file must contain a [general] section, with one only entry, model, describing the preselected button set.

Then, it must contain at least the preselected button set, plus as many others as the user wants, in the format:

label=roll descriptor
label 2=roll descriptor 2

This sets describe predefined roll buttons, which are shown on the UI for common rolls.

If this file becomes corrupted, simply erasing it will cause the program to create a new one, with only the "basic" button set.


  1. Fork it (
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create a new Pull Request


You can’t perform that action at this time.