README

A member's dice appearance — skins, colours, materials and owned dice — applied to the roller, its numbers kept readable.

A member chooses how their dice look: a skin for all their dice, another for their d20, or a die of a set they own in their collection. The library gives the roller, for each die it shows, the appearance to draw — the colour of the faces, the colour of the numbers and pips, the material, the texture — as CSS custom properties, data attributes or plain values for a renderer that reads JSON. The appearance never changes the randomness: it only dresses the dice the server rolled.

Every skin keeps its numbers readable: its ink stands out from its faces at 4.5:1 at least, the contrast WCAG 2.2 asks of text at level AA, and a skin under it is refused when it is defined. A die of a set gets the black or white ink that stands out most on its colour. For a viewer who asks for high contrast, the numbers are kept at 7:1 at least, on solid faces without texture, and a die that cannot reach it is shown black on white.

It is a plain PHP library. The skins come from the site — eight base skins ship with the library, and a site adds its own from JSON —, the members' choices from a store the application provides, and the owned dice from tilttek/collections, read through a port. An adapter gives the appearance to the roller of tilttek/dice-bundle.

Status

Part	State
`Color`, `Material`, `TextureReference`: colours with their WCAG luminance and contrast, materials, texture keys	Implemented and tested
`Skin`, `SkinLook`, `SkinDefinitions`, `BaseSkins`: readable skins, their looks by type of dice, read from JSON	Implemented and tested
`DiceSkins`, `DieAppearance`: the members' choices and the appearance of each die, in standard or high contrast	Implemented and tested
`Contract\SkinCatalog`, `Contract\SkinChoiceStore`, `Contract\OwnedDice`, with memory stores	Implemented and tested
`Collections\ShelfOwnedDice`: the owned dice read from `tilttek/collections`	Implemented and tested
`DiceBundle\DiceSkinsAppearance`: the appearance given to the roller of `tilttek/dice-bundle` 0.2	Implemented and tested
Exceptions under one `DiceSkinsException` interface	Implemented and tested

Documentation

Document	What it covers
Installation	Requirements, installing and wiring.
Usage	Skins, choices, owned dice and the appearance given to the roller.
Accessibility	The contrast of the numbers, high contrast, and what the renderer keeps.
Rolling with tilttek/dice-bundle	The adapter of the roller's appearance port, and how to declare it.
Extension points	What an application gives the library.
Testing	The library's tests, fuzz target and benchmarks.
Reference	Every type of the library, with its role, and its exceptions.

Quick start

use Phil\Resource\ResourceReference;
use Tilttek\DiceSkins\Accessibility;
use Tilttek\DiceSkins\DiceSkins;
use Tilttek\DiceSkins\Store\FixedSkinCatalog;
use Tilttek\DiceSkins\Store\InMemorySkinChoiceStore;

$skins = new DiceSkins(FixedSkinCatalog::withBase(), new InMemorySkinChoiceStore());
$member = ResourceReference::of('member', '42');

$skins->choose($member, 'crimson');           // all their dice
$skins->choose($member, 'gold', 20);          // and their d20

$d20 = $skins->appearance($member, 20);
$d20->style();             // "--tilttek-dice-color: #d4a017; --tilttek-dice-ink: #1a1a1a"
$d20->dataAttributes();    // ['data-dice-appearance' => 'Gold', 'data-dice-sides' => '20', 'data-dice-material' => 'metal']

$skins->appearance($member, 6, Accessibility::HighContrast)->toArray();

Requirements

PHP 8.5 or later, phil/resource and tilttek/collections 0.1; tilttek/dice-bundle 0.2.0-alpha or later for its roller's appearance.

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-skins

Package info

Security

Statistics