Skip to content
Tilttek
Français

tilttek/dice-probability

✅ published

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

PartState
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 firstImplemented and tested
At least, at most, mean, variance, standard deviation, a validator's probabilityImplemented and tested
Events: counts of a face or a validator, dice of a kind, straights, all equal, all different, all matching, composedImplemented and tested
Two expressions comparedImplemented and tested
Explosions to a depth with what remains; seeded estimates with their marginImplemented and tested
Exact numbers of any sizeImplemented and tested

Documentation

DocumentWhat it covers
InstallationRequirements, installing and a first distribution.
DistributionsProbabilities::distribution(), Distribution, and what is computed exactly.
Eventschance(), the events, the reference example and Faces.
Comparing two expressionscompare() and Versus.
Explosions and estimatesSettings, the depth of explosions, the estimates and their margin.
Exact numbersNatural and Fraction.
ExceptionsProbabilityException, CannotCompute and the invalid arguments.
Extension pointsEvents and dice of the application.
TestingThe library's tests, and how to test code that uses it.
ReferenceEvery 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.

License

MIT, © Philippe Gamache, doing business as Le Gnome Archiviste; a Tilttek project. See LICENSE.