tilttek/dice

tilttek/dice reads a dice expression such as 4d6kh3, d20 adv, 3d10!!, 6d10>=7f1, 8d10c[>=6]-@c[=1], ceil(1d6/3), (1d8+2)*2, 1d4 or 8d10; @1c[>=6]; "$2 successes", refuses an invalid one with the position of the error, writes it back in a canonical form, and rolls it. Instructions refer to each other, branch on a result, draw from lists of texts and write sentences: a result is a number, a text or a list. A roll keeps each die, each reroll, each explosion, what was kept or dropped, and each total. It also rolls custom dice whose faces are symbols, reads and writes the notation of other languages (2W6 in German), reads a command of Rolisteam's DiceParser, resolves the macros an application keeps ($attack), writes an expression in the dialect of a virtual tabletop, and makes rolls that anyone can verify or that replay die for die. It does not draw dice, animate them, keep a journal or know who rolls: a page, a bundle or an application does that.

It is for any PHP code that rolls dice for people: a dice roller page, a play-by-post forum, a character sheet, a virtual table, a game book. tilttek/dice-bundle integrates it with Symfony; an application without Symfony takes the library alone.

It is a plain PHP library with no dependency beyond the ctype, mbstring and sodium extensions. Its randomness is a Random\Randomizer the caller passes: a secure engine in production, a fixed seed in tests, the seed of a verifiable or replayable roll. The parser is a hand-written lexer and recursive-descent parser, without regular expressions on the input.

The design is small: a DiceParser gives a Pool of expression trees — a RolisteamReader too, from DiceParser's notation —, a Roller rolls a pool into a PoolResult, a NotationWriter and the Dialect classes write a pool back, FairRoller and Replayer make verifiable and replayable rolls, and DiceRoller puts them in one object.

Status

Documentation

Quick start

composer require tilttek/dice

use Random\Engine\Secure;
use Random\Randomizer;
use Tilttek\Dice\DiceRoller;

$dice = new DiceRoller();
$pool = $dice->parse('4D6KH3, d20 adv');
$randomizer = new Randomizer(new Secure());

$pool->canonical();                                   // "4d6kh3, 2d20kh1"
$result = $dice->roll($pool, $randomizer);
$result->totals();                                    // [14, 17], for instance
$dice->translate($pool, 'roll20')->text();            // "/r 4d6kh3\n/r 2d20kh1"
$dice->write($dice->parse('2W6+1', 'de'));            // "2d6+1"
$dice->roll($dice->parse('1d6/3'), $randomizer, RoundingMode::PositiveInfinity)->totals(); // [2], rounded up
$dice->roll($dice->parse('1d20i[>=15]{"hit"}{"miss"}'), $randomizer)->outputs();         // ["miss"], for instance

Requirements

PHP 8.5 or later, with the ctype, mbstring and sodium extensions.

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.