README

The exact probabilities of a dice expression — every total as a fraction, and the chance of a double.

tilttek/dice-probability computes what an expression of tilttek/dice can give and how likely each value is: 4d6kh3, 2d20kh1, 6d10>=7f1, (1d4)d6, 1d6!. Each probability is an exact fraction over the ways to roll — 6/36 for a 7 on 2d6 —, with the probability of at least and at most each value, the mean and the standard deviation. It also gives the probability of events on the faces of a set of dice — at least one 1, exactly two sixes, a double, a straight, all different, and their combinations — and compares two expressions, an attack against a defence. Explosions are followed to a depth, the probability of going further stated; past a size, or for the few constructs it does not follow, a seeded estimate takes over, marked as estimated, with its margin.

It is for any PHP code that explains dice to people: a probability page, a game designer weighing two mechanics, a character sheet that shows the odds of a roll. tilttek/dice-probability-bundle integrates it with Symfony, with a table, a chart and a Live Component.

It is a plain PHP library that depends only on tilttek/dice. Its large numbers are its own, without bcmath or gmp. Sums of dice are convolutions, a plain die summed by a sliding window; keep and drop run over the sorted multisets of the dice, never over every roll.

Status

Part	State
Exact distributions: arithmetic, functions, dice, rerolls, explosions, floors, transformations, filters, keep and drop, successes and failures, judgements of the whole set, counts and sides rolled first	Implemented and tested
At least, at most, mean, variance, standard deviation, a validator's probability	Implemented and tested
Events: counts of a face or a validator, dice of a kind, straights, all equal, all different, all matching, composed	Implemented and tested
Two expressions compared	Implemented and tested
Explosions to a depth with what remains; seeded estimates with their margin	Implemented and tested
Exact numbers of any size	Implemented and tested

Documentation

Document	What it covers
Installation	Requirements, installing and a first distribution.
Distributions	`Probabilities::distribution()`, `Distribution`, and what is computed exactly.
Events	`chance()`, the events, the reference example and `Faces`.
Comparing two expressions	`compare()` and `Versus`.
Explosions and estimates	`Settings`, the depth of explosions, the estimates and their margin.
Exact numbers	`Natural` and `Fraction`.
Exceptions	`ProbabilityException`, `CannotCompute` and the invalid arguments.
Extension points	Events and dice of the application.
Testing	The library's tests, and how to test code that uses it.
Reference	Every type of the library, with its role.

Quick start

composer require tilttek/dice-probability

use Tilttek\Dice\DiceRoller;
use Tilttek\DiceProbability\Event\AnyOf;
use Tilttek\DiceProbability\Event\Count;
use Tilttek\DiceProbability\Event\OfAKind;
use Tilttek\DiceProbability\Probabilities;

$dice = new DiceRoller();
$probabilities = new Probabilities();

$distribution = $probabilities->distribution($dice->parse('2d6'));
(string) $distribution->probability(7);                // "6/36"
(string) $distribution->atLeast(10)->reduced();         // "1/6"

$oneOrDouble = new AnyOf(Count::atLeastOne(1), OfAKind::double());
(string) $probabilities->chance($oneOrDouble, $dice->parse('3d6'))->probability;   // "156/216"

(string) $probabilities->compare($dice->parse('1d20+5'), $dice->parse('2d10+4'))->first->reduced(); // "1/2"

Requirements

PHP 8.5 or later, and tilttek/dice.

Contributing

Contributions are welcome on the PHIL monorepo: read the contribution guide and the code of conduct. Report a vulnerability privately, as the security policy explains, never in a public issue.

tilttek / dice-probability

Package info

Security

Statistics