Download the PHP package daverichards00/diceroller without Composer

dice-roller

• Dice
• DiceShaker
• Examples
• Contribution

Dice

A single dice can be created and rolled multiple times.

Creating a Dice

Create a standard numeric Dice by passing a single number into the constructor:

Create a Dice with custom sides by passing an array of numbers or strings:

Rolling

You can roll a Dice and get the value that was rolled:

Custom Rollers

You can customise the random number generation by injecting an implementation of daverichards00\DiceRoller\Roller\RollerInterface.

There are two preset rollers:

Creating your own Roller

You can create your own roller by implementing the RollerInterface. This requires you to implement the method public function roll(int $min, int $max): int, which takes two integers, a min and a max, and returns a random int within the range (inclusive). Below is an example:

History

You can see the history of rolls:

Exceptions

The most common exceptions that are thrown are \InvalidArgumentException and daverichards00\DiceRoller\Exception\DiceException. DiceException extends \RuntimeException, and will be thrown when you would expect a runtime exception to be thrown.

DiceShaker

A collection of Dice can be created by using a DiceShaker.

Creating a DiceShaker

When creating a DiceShaker you need to specify the Dice that will be used. This can be done by passing an array of Dice objects:

It can also be done by passing an array of scalar values, that will be used to create the instances of Dice:

Or, you can pass a single Dice/scalar and a quantity:

Note: When passing an instance of Dice and a quantity, the passed instance will be added as the first dice, then subsequent dice will be clones of the passed instance.

Rolling

All the Dice in the DiceShaker can be rolled:

Getters

There are numerous ways to get and interact with the values of the rolled Dice:

Selectors

Selectors can be used to perform actions on, or get values from, a subset of the Dice in the DiceShaker. A selector can be created by the factory and passed to the action/getter:

There are various selectors available:

Custom selectors can also be used, as long as they implement the interface: daverichards00\DiceRoller\Selector\DiceSelectorInterface:

Actions

There are some actions that can be performed on the Dice in the DiceShaker:

Exceptions

\daverichards00\DiceRoller\Exception\DiceShakerException extends \RuntimeException and will be thrown if trying to perform an operation when there are no Dice in the DiceShaker, or trying to use a numeric-only getter when non-numeric Dice are present.

Examples

2d6

2d6 + 1d8

4d6-L

d% (Percentile)

Note: In the last 2 examples we're adding 1 to the result to alter the range from 0-99 to 1-100. Programmatically, this is easier than treating 0 as 100 and still results in an evenly balanced random number between 1 and 100.

3 x (2d6+4)

8d10k6 or 8d10+H6 or 8d10-L2

Number of results >= 8 from 6d10

4dF (Fudge)

D66 or d6x10+d6

Contribution

Please feel free to let me know if you think there is anything that I have missed or any way to improve usability or functionality. It would be great to understand how people use, or would like to use, this package. I'm more than happy to update and expand this project if I think it will be useful :)