A library for simulating dice rolls written in PHP.

v2.2.0 2022-01-02 04:31 UTC


CI Code Quality Codacy Badge Docs Status

Latest Stable Version PHP Versions Supported License Total Downloads Slack

Got Dice?

Run your dice notation using Docker:

$ docker run ouxsoft/luckbydice:latest bin/luckbydice d3,4d6+1,5d+1*2

CLI Test Example


Install using Composer:

$ composer require ouxsoft/luckbydice

Basic Usage


use Ouxsoft\LuckByDice\Factory\TurnFactory;

$turn = TurnFactory::getInstance();
echo $turn->roll(); 

// we should be luckier with this next roll
echo $turn->roll();


LuckByDice is a PHP library for simulating dice rolls written in PHP. In addition to emulating standard dice rolls from dice notation, it can also emulate luck.

Rolls made with luck enabled have a natural ebb and flow to roll outcomes. Rolls made with higher luck are more likely to roll higher values. Luck is well suited for use with character's luck stat, which may feature unnatural modification.

Chart Test

This graph illustrates 10,000 consecutive 10d10 rolls to aid in statistical analysis. Notice how outcome impacts luck and vice versa.

Chart Test Example



Matthew Heroux.
See also the list of contributors who participated in this project.


LuckByDice is open source software project. If you find a problem or want to discuss new features or improvements create an issue, and/or if possible create a pull request. For details, see CONTRIBUTING.md.


Thanks to Zachary Whitcomb-Paulson for dice notation expertise.