tilttek / dice-jail
Send unlucky dice to jail, then check them with a fair statistical test, explained plainly, that never calls a die loaded without the evidence.
Requires
- php: >=8.5
- ext-mbstring: *
- psr/clock: ^1.0
- tilttek/dice: ^0.2@dev || ^0.3@dev
- tilttek/dice-probability: ^0.1@dev
Requires (Dev)
- phpunit/phpunit: ^13.4
- symfony/clock: ^8.2
Suggests
None
Provides
None
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-11-21 03:06:01 UTC
README
The jail for unlucky dice, and the statistics behind it: an honest goodness-of-fit test, explained plainly.
A die that keeps rolling ones goes to jail: a player sends it there for an evening or until they release it, and the jail keeps the history of each die. It is a gesture of play — jailing needs no proof and changes nothing in how the die rolls.
The statistics are what a player shows the table. GoodnessOfFit runs Pearson's chi-squared test on the rolls of one
die against the exact probabilities of a fair one — a uniform die, or any distribution tilttek/dice-probability
computes —, refuses to judge before every face is expected five times, and gives a p-value and a verdict:
« not enough rolls », « nothing unusual », « somewhat unusual » or « very unusual ». Explanation says it in plain
English or French, with the average roll beside the expected one. No sentence ever says a die is loaded: the most
unusual verdict asks for a look at the die, or for new rolls, and the rolls of digital dice are said to come from a
generator that serves every die alike.
It is for a table that plays online or writes down its physical rolls: a game master's screen, a dice tower, a
character sheet. It is a plain PHP library on tilttek/dice and tilttek/dice-probability; the application keeps the
history and the rolls through two ports.
Status
| Part | State |
|---|---|
Jail\Warden: jailing for a sentence or until release, releasing, the dice in jail, the history |
Implemented and tested |
Jail\Inmate, Jail\JailEvent, Jail\EventKind, Jail\Evidence: the sentence, the history and the statistics shown |
Implemented and tested |
Statistics\GoodnessOfFit, Statistics\FitResult, Statistics\FaceCount, Statistics\Verdict: the chi-squared test |
Implemented and tested |
Statistics\Tally, Statistics\ExpectedFaces: the rolls counted, the fair die from a range or a distribution |
Implemented and tested |
Statistics\Explanation, Statistics\Language, Statistics\Origin: the verdict in plain English and French |
Implemented and tested |
Statistics\DieAssessor, Contract\RollSource, Store\InMemoryRollSource: the test from recorded rolls |
Implemented and tested |
Contract\JailStore, Store\InMemoryJailStore |
Implemented and tested |
A roll source reading the roll journal of tilttek/dice-bundle |
Not started |
Documentation
| Document | What it covers |
|---|---|
| Installation | Requirements, installing and wiring. |
| The jail | Jailing, sentences, releases, the history, and what the jail is not. |
| The statistics | The chi-squared test, the minimum of rolls, the verdicts and how to read them honestly. |
| Explanations | The sentences in English and French, and what they never say. |
| Extension points | What an application gives the library. |
| Exceptions | DiceJailException and its exceptions. |
| Testing | The library's tests, fuzz target and benchmarks. |
| Reference | Every public type, with its role. |
Quick start
use Symfony\Component\Clock\NativeClock; use Tilttek\DiceJail\Jail\Evidence; use Tilttek\DiceJail\Jail\Warden; use Tilttek\DiceJail\Statistics\ExpectedFaces; use Tilttek\DiceJail\Statistics\Explanation; use Tilttek\DiceJail\Statistics\GoodnessOfFit; use Tilttek\DiceJail\Statistics\Language; use Tilttek\DiceJail\Statistics\Tally; use Tilttek\DiceJail\Store\InMemoryJailStore; $result = new GoodnessOfFit()->test(Tally::of($rollsOfTheBlueD20), ExpectedFaces::uniform(20)); $result->verdict; // Verdict::NothingUnusual, most of the time new Explanation()->explain($result, Language::French); // « Rien d’inhabituel sur 120 lancers : … » $warden = new Warden(new InMemoryJailStore(), new NativeClock()); $warden->jail('member-7', 'd20:blue', 'Three natural ones in a row.', evidence: Evidence::of($result)); $warden->release('member-7', 'd20:blue', 'It has served its time.');
Requirements
PHP 8.5 or later, with mbstring; tilttek/dice 0.2 or 0.3 and tilttek/dice-probability 0.1; a psr/clock implementation.
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.